qwen-code/integration-tests/cli/notebook-edit.test.ts
jinye a3c8986e59 docs(serve): v0.16-alpha known limits + SDK QWEN_SERVER_TOKEN env fallback (PR 27) (#4473)
* docs(serve): v0.16-alpha known limits + SDK QWEN_SERVER_TOKEN env fallback (PR 27)

First PR in the F5 release chain (PR 27 → 28 → 30a → 31) per the
2026-05-24 v0.16-alpha scope freeze in #4175 (text-only chat / coding
+ local-only deployment).

## SDK ergonomic micro-change (~50 LOC + 4 tests)

`DaemonClient` constructor falls back to `QWEN_SERVER_TOKEN` env
var when `opts.token` is absent — closes the asymmetry where the
daemon side already honors this var (--token CLI flag fallback,
already in main since PR 15) but the SDK forced clients to thread
it through every construction.

Properties:
- Browser-safe via `globalThis.process` indirection (the SDK is
  imported by @qwen-code/webui; literal process.env access would
  explode at module load on browser bundles)
- Whitespace stripped (matches daemon-side trim — handy for
  `export QWEN_SERVER_TOKEN=\"\$(cat token.txt)\"` where cat adds a
  trailing newline)
- Empty / whitespace-only treated as unset (a stale
  `export QWEN_SERVER_TOKEN=\"\"` won't accidentally send
  Authorization: Bearer with no token)
- Resolved at construction, not lazily per-request (later
  process.env mutations don't affect already-built clients)
- Explicit opts.token wins over env

Tests: 4 new in DaemonClient.test.ts `bearer auth` describe
covering env fallback / explicit-wins / empty-treated-unset /
whitespace-stripped. Plus a defensive snapshot/restore on the
existing 'omits Authorization when no token' test so an
inherited test-runner export of QWEN_SERVER_TOKEN doesn't turn
that assertion into a false positive.

This SDK fallback is the entire ergonomic replacement for PR 29's
SDK env/file fallback. PR 29's other features (auto-gen daemon
token, instance-path keying, stale cleanup) remain deferred to
v0.16.x — all are DX improvements over the boot-time security gate
already shipped in PR 15.

## v0.16-alpha docs (~120 LOC markdown)

- docs/users/qwen-serve.md: new "v0.16-alpha known limits" section
  enumerating product surface (text-only ✅, multimodal ❌),
  deployment surface (local launchers ✅, containerized ❌, multi-
  daemon ❌, BYO-token ✅), and hardening posture (boot security
  gate ✅, mutation gate ✅, MCP guardrails ✅, prompt absolute
  deadline ⏸️, rate limiting ⏸️, --max-body-size ⏸️). Adds an
  alpha banner at the top of the file.

- docs/developers/examples/daemon-client-quickstart.md:
  documents the SDK env fallback in both the Hello-daemon
  intro and the Authentication section, with the "export +
  no-token-arg" recommended path called out for local dev.

Verification: 125/125 DaemonClient.test.ts pass (121 existing +
4 new); 4/4 daemon-public-surface.test.ts pass (constructor
signature unchanged); tsc clean on packages/sdk-typescript;
eslint --max-warnings 0 clean on touched .ts files.

Part of #4175.

* fix(sdk): #4473 round 1 fold-in — 2 copilot doc threads adopted

T1 [copilot DaemonClient.ts:144 — stale line refs in readTokenFromEnv
  JSDoc]: removed `runQwenServe.ts:175` (token resolution actually
  lives at line 302-318 today, would drift again on next refactor)
  and `docs/users/qwen-serve.md:173`. Replaced with stable
  symbol/section references ("runQwenServe token-resolution path";
  "qwen-serve user guide CLI flags section").

T2 [copilot daemon-client-quickstart.md:33 — `~/.qwen/server-token`
  implies built-in path that doesn't exist]: PR 27 explicitly defers
  token auto-generation + file-store fallback (PR 29 deferred features).
  The example incorrectly suggested a standard file location.
  Replaced with two explicit user-managed alternatives:
  - `openssl rand -hex 32` one-shot
  - `cat ./my-token-file` user-managed file

Both threads were accurate suggestions caught at the right time
(zero behavior change; pure docstring/example accuracy).

Verification: 125/125 DaemonClient tests pass; tsc + eslint clean
on touched files.
2026-05-27 10:31:34 +08:00

240 lines
6.7 KiB
TypeScript

/**
* @license
* Copyright 2026 Qwen Team
* SPDX-License-Identifier: Apache-2.0
*/
import path from 'node:path';
import { afterEach, describe, expect, it } from 'vitest';
import {
TestRig,
createToolCallErrorMessage,
printDebugInfo,
validateModelOutput,
} from '../test-helper.js';
type NotebookCell = {
id?: string;
cell_type: 'code' | 'markdown' | 'raw';
metadata: Record<string, unknown>;
source: string | string[];
execution_count?: number | null;
outputs?: unknown[];
};
type NotebookContent = {
cells: NotebookCell[];
metadata: Record<string, unknown>;
nbformat: number;
nbformat_minor: number;
};
const sourceText = (source: string | string[]) =>
Array.isArray(source) ? source.join('') : source;
const promptPath = (filePath: string) => filePath.split(path.sep).join('/');
const readNotebook = (rig: TestRig, fileName: string): NotebookContent =>
JSON.parse(rig.readFile(fileName)) as NotebookContent;
const baseNotebook = (cells: NotebookCell[]): NotebookContent => ({
cells,
metadata: {
kernelspec: {
display_name: 'Python 3',
language: 'python',
name: 'python3',
},
language_info: {
name: 'python',
},
},
nbformat: 4,
nbformat_minor: 5,
});
const expectReadThenNotebookEdit = (rig: TestRig, result: string) => {
const logs = rig.readToolLogs();
const foundTools = logs.map((t) => t.toolRequest.name);
const readIndex = foundTools.findIndex((name) => name === 'read_file');
const notebookEditIndex = foundTools.findIndex(
(name) => name === 'notebook_edit',
);
if (readIndex === -1 || notebookEditIndex === -1) {
printDebugInfo(rig, result, { foundTools });
}
expect(
readIndex,
createToolCallErrorMessage('read_file', foundTools, result),
).toBeGreaterThanOrEqual(0);
expect(
notebookEditIndex,
createToolCallErrorMessage('notebook_edit', foundTools, result),
).toBeGreaterThan(readIndex);
};
const expectNoSuccessfulRawNotebookWrites = (
rig: TestRig,
notebookFileName: string,
) => {
const rawNotebookWrites = rig
.readToolLogs()
.filter(
(log) =>
['edit', 'write_file'].includes(log.toolRequest.name) &&
log.toolRequest.success &&
log.toolRequest.args.includes(notebookFileName),
);
expect(rawNotebookWrites).toEqual([]);
};
describe('notebook_edit integration', () => {
let rig: TestRig;
afterEach(async () => {
await rig?.cleanup();
});
it('replaces a code cell after reading the notebook and clears stale outputs', async () => {
rig = new TestRig();
await rig.setup('notebook edit replace code cell clears outputs');
const fileName = 'analysis.ipynb';
const notebookPath = rig.createFile(
fileName,
JSON.stringify(
baseNotebook([
{
id: 'intro',
cell_type: 'markdown',
metadata: {},
source: ['# Analysis\n'],
},
{
id: 'load-data',
cell_type: 'code',
metadata: {},
source: ['old_value = 1\n', 'print(old_value)\n'],
execution_count: 7,
outputs: [
{
output_type: 'stream',
name: 'stdout',
text: ['1\n'],
},
],
},
]),
null,
1,
),
);
const prompt = `Read the notebook at ${promptPath(notebookPath)} with read_file first.
Then use notebook_edit, not edit or write_file, to replace the code cell whose id is load-data.
Set the new source exactly to:
result = 41 + 1
print(result)
Do not change any other cell.`;
const result = await rig.run(prompt);
expectReadThenNotebookEdit(rig, result);
expectNoSuccessfulRawNotebookWrites(rig, fileName);
validateModelOutput(result, null, 'Notebook replace');
const notebook = readNotebook(rig, fileName);
const target = notebook.cells.find((cell) => cell.id === 'load-data');
expect(target).toBeDefined();
expect(target?.cell_type).toBe('code');
expect(sourceText(target!.source).trimEnd()).toBe(
'result = 41 + 1\nprint(result)',
);
expect(target?.execution_count).toBeNull();
expect(target?.outputs).toEqual([]);
expect(sourceText(notebook.cells[0]!.source)).toBe('# Analysis\n');
});
it('inserts a markdown cell and deletes a target cell using notebook_edit', async () => {
rig = new TestRig();
await rig.setup('notebook edit insert and delete cells');
const fileName = 'workflow.ipynb';
const notebookPath = rig.createFile(
fileName,
JSON.stringify(
baseNotebook([
{
id: 'intro',
cell_type: 'markdown',
metadata: {},
source: ['# Workflow\n'],
},
{
id: 'remove-me',
cell_type: 'markdown',
metadata: {},
source: ['This temporary cell should be deleted.\n'],
},
{
id: 'calculate',
cell_type: 'code',
metadata: {},
source: ['value = 10\n'],
execution_count: null,
outputs: [],
},
]),
null,
1,
),
);
const insertedMarkdown =
'## Inserted Note\nThis cell was inserted by NotebookEdit.';
const prompt = `Read the notebook at ${promptPath(notebookPath)} with read_file first.
Then use notebook_edit, not edit or write_file, for both changes:
1. Insert a markdown cell after the cell whose id is intro. Its source must be exactly:
${insertedMarkdown}
2. Delete the cell whose id is remove-me.
Do not change the calculate code cell.`;
const result = await rig.run(prompt);
expectReadThenNotebookEdit(rig, result);
expectNoSuccessfulRawNotebookWrites(rig, fileName);
validateModelOutput(result, null, 'Notebook insert/delete');
const successfulNotebookEdits = rig
.readToolLogs()
.filter(
(log) =>
log.toolRequest.name === 'notebook_edit' && log.toolRequest.success,
);
expect(successfulNotebookEdits.length).toBeGreaterThanOrEqual(2);
const notebook = readNotebook(rig, fileName);
const cellIds = notebook.cells.map((cell) => cell.id);
const insertedCell = notebook.cells.find((cell) =>
sourceText(cell.source).includes('Inserted Note'),
);
expect(cellIds).toHaveLength(3);
expect(cellIds).not.toContain('remove-me');
expect(notebook.cells[0]?.id).toBe('intro');
expect(insertedCell).toBeDefined();
expect(insertedCell?.cell_type).toBe('markdown');
expect(sourceText(insertedCell!.source).trimEnd()).toBe(insertedMarkdown);
expect(notebook.cells.at(-1)?.id).toBe('calculate');
expect(sourceText(notebook.cells.at(-1)!.source)).toBe('value = 10\n');
});
});