@cjhyy/code-shell-server 0.9.21 → 0.9.23

package/dist/serve/settings-recovery-cli.js

@@ -0,0 +1,128 @@
+import { parseArgs } from "node:util";
+const HELP = `Usage: code-shell-settings-recovery <inspect|repair|restore> [options]
+
+Offline administrator recovery for a stopped project's settings.
+Stop the project and all its workers before repair or restore.
+This command does not start a server, authenticate remote users or stop workers.
+
+Options:
+  --project <directory>        Actual project directory (default: current directory)
+  --scope <project|local>      Configuration layer (default: project)
+  --from <file>                Complete reviewed JSON candidate (inspect or repair)
+  --expected-revision <sha256> Revision returned by inspect (repair or restore)
+  --candidate-sha256 <sha256>  Candidate hash returned by inspect (repair)
+  --backup-id <id>             Backup returned by repair/restore (restore)
+  -h, --help                   Show this help without reading configuration
+
+Inspection reports metadata and hashes, never configuration values.
+Repair preserves original bytes before replacement. Restore also backs up current
+bytes; restoring a damaged original restores that fault too. Keep backups private.
+`;
+export function parseSettingsRecoveryArgs(argv, cwd) {
+    const invalid = () => new Error("Invalid recovery arguments; use --help for usage.");
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            strict: true,
+            allowPositionals: true,
+            tokens: true,
+            options: {
+                project: { type: "string" },
+                scope: { type: "string" },
+                from: { type: "string" },
+                "expected-revision": { type: "string" },
+                "candidate-sha256": { type: "string" },
+                "backup-id": { type: "string" },
+                help: { type: "boolean", short: "h" },
+            },
+        });
+    }
+    catch {
+        // Parser errors can reflect unrecognized argument values. Do not echo them.
+        throw invalid();
+    }
+    const { values, positionals, tokens } = parsed;
+    const names = new Set();
+    for (const token of tokens ?? []) {
+        if (token.kind !== "option")
+            continue;
+        if (names.has(token.name))
+            throw invalid();
+        names.add(token.name);
+    }
+    const action = positionals[0];
+    if (positionals.length > 1 || (action && !["inspect", "repair", "restore"].includes(action)))
+        throw invalid();
+    if (values.help)
+        return { action: "help" };
+    if (!action)
+        throw invalid();
+    const allowed = new Set(["project", "scope"]);
+    if (action === "inspect" || action === "repair")
+        allowed.add("from");
+    if (action !== "inspect")
+        allowed.add("expected-revision");
+    if (action === "repair")
+        allowed.add("candidate-sha256");
+    if (action === "restore")
+        allowed.add("backup-id");
+    for (const name of names)
+        if (!allowed.has(name))
+            throw invalid();
+    const value = (name, required = false) => {
+        const result = values[name];
+        if (result === undefined && !required)
+            return undefined;
+        if (typeof result !== "string" || !result.trim())
+            throw invalid();
+        return result;
+    };
+    const scope = value("scope") ?? "project";
+    if (scope !== "project" && scope !== "local")
+        throw invalid();
+    const target = { cwd: value("project") ?? cwd(), scope };
+    if (action === "inspect")
+        return { action, ...target, candidatePath: value("from") };
+    const expectedRevision = value("expected-revision", true);
+    if (!/^[a-f0-9]{64}$/.test(expectedRevision))
+        throw invalid();
+    if (action === "repair") {
+        const candidateSha256 = value("candidate-sha256", true);
+        if (!/^[a-f0-9]{64}$/.test(candidateSha256))
+            throw invalid();
+        return {
+            action,
+            ...target,
+            candidatePath: value("from", true),
+            expectedRevision,
+            candidateSha256,
+        };
+    }
+    return { action: "restore", ...target, backupId: value("backup-id", true), expectedRevision };
+}
+export async function runSettingsRecoveryCli(argv = process.argv.slice(2), io = {}) {
+    const write = io.write ?? ((text) => process.stdout.write(text));
+    const error = io.error ?? ((text) => process.stderr.write(text));
+    try {
+        const args = parseSettingsRecoveryArgs(argv, io.cwd ?? (() => process.cwd()));
+        if (args.action === "help") {
+            write(HELP);
+            return 0;
+        }
+        // Load only the reviewed Host recovery operations, after argument validation.
+        // In particular, do not start serve/bootstrap or require TUI/model setup.
+        const core = await import("@cjhyy/code-shell-core/internal");
+        const result = args.action === "inspect"
+            ? core.inspectProjectSettingsRecovery(args)
+            : args.action === "repair"
+                ? core.repairProjectSettings(args)
+                : core.restoreProjectSettings(args);
+        write(JSON.stringify(result, null, 2) + "\n");
+        return 0;
+    }
+    catch (cause) {
+        error(`[settings-recovery] ${cause instanceof Error ? cause.message : "Recovery failed"}\n`);
+        return 1;
+    }
+}

package/dist/session-http-responses.d.ts

@@ -0,0 +1,7 @@
+import type { ServerResponse } from "node:http";
+/** Response lifetimes are session-owned; accepted background work is not. */
+export declare function createSessionHttpResponses(): {
+    track(sessionId: string, response: ServerResponse): void;
+    cancelOwner: (sessionId: string) => void;
+    clear(): void;
+};

package/dist/session-http-responses.js

@@ -0,0 +1,40 @@
+/** Response lifetimes are session-owned; accepted background work is not. */
+export function createSessionHttpResponses() {
+    const owners = new Map();
+    function cancelOwner(sessionId) {
+        const responses = owners.get(sessionId);
+        if (!responses)
+            return;
+        for (const [response, release] of responses) {
+            release();
+            response.destroy();
+        }
+    }
+    return {
+        track(sessionId, response) {
+            if (response.destroyed || response.writableFinished)
+                return;
+            let responses = owners.get(sessionId);
+            if (!responses)
+                owners.set(sessionId, (responses = new Map()));
+            const owned = responses;
+            const release = () => {
+                response.off("finish", release);
+                response.off("close", release);
+                owned.delete(response);
+                if (owned.size === 0)
+                    owners.delete(sessionId);
+            };
+            owned.set(response, release);
+            // A handler may return before its stream finishes. Follow the actual
+            // response, so revocation still aborts the upstream pipeline and its files.
+            response.once("finish", release);
+            response.once("close", release);
+        },
+        cancelOwner,
+        clear() {
+            for (const sessionId of owners.keys())
+                cancelOwner(sessionId);
+        },
+    };
+}

package/dist/worker-bridge-core.d.ts

@@ -38,8 +38,11 @@ export type WorkerRpcOutcome = {
 };
 export interface WorkerRequestOptions {
     /** Wire id for the frame. Caller mints it (must be unique while pending). */
-    id: string;
+    id: string | number;
     timeoutMs: number;
+    /** For agent/run, timeout covers admission only. A matching runAccepted
+     * transfers ownership to completion/exit; requires failFast + settleOnExit. */
+    waitForRunCompletion?: boolean;
     /**
      * true: the matching response line is consumed here and NOT dispatched to
      * line listeners (host-internal RPC, e.g. pet snapshots). false: the line
@@ -156,6 +159,11 @@ export declare class WorkerBridgeCore {
      * to map onto its own semantics.
      */
     request(method: string, params: unknown, options: WorkerRequestOptions): Promise<WorkerRpcOutcome>;
+    /** Request shutdown and retain ownership until this exact child exits.
+     * Does not resolve merely because SIGTERM was sent; an uncooperative child
+     * remains owned so a caller cannot start competing work prematurely.
+     */
+    stopAndWait(): Promise<void>;
     /** Graceful shutdown: SIGTERM the worker (no-op when none is alive). */
     kill(): void;
 }

package/dist/worker-bridge-core.js

@@ -197,6 +197,11 @@ export class WorkerBridgeCore {
         }
         if (!msg || typeof msg !== "object" || Array.isArray(msg))
             return false;
+        if (msg.method === "agent/runAccepted" &&
+            (typeof msg.params?.requestId === "string" || typeof msg.params?.requestId === "number")) {
+            this.pendingRequests.get(msg.params.requestId)?.acceptRun?.(msg.params.sessionId);
+            return false;
+        }
         if (msg.id === undefined || msg.id === null)
             return false;
         const pending = this.pendingRequests.get(msg.id);
@@ -268,6 +273,13 @@ export class WorkerBridgeCore {
      */
     request(method, params, options) {
         const { id } = options;
+        if (options.waitForRunCompletion &&
+            (method !== "agent/run" || !options.failFast || !options.settleOnExit)) {
+            return Promise.resolve({
+                status: "sendFailed",
+                error: new Error("Completion tracking requires agent/run, failFast and settleOnExit"),
+            });
+        }
         return new Promise((resolve) => {
             let settled = false;
             const settle = (outcome) => {
@@ -289,6 +301,16 @@ export class WorkerBridgeCore {
                 consume: options.consume === true,
                 settleOnExit: options.settleOnExit === true,
                 settle,
+                ...(options.waitForRunCompletion
+                    ? {
+                        acceptRun: (sessionId) => {
+                            const expected = params?.sessionId;
+                            if (typeof sessionId === "string" && (!expected || sessionId === expected)) {
+                                clearTimeout(timer);
+                            }
+                        },
+                    }
+                    : {}),
             });
             let rawFrame;
             try {
@@ -343,6 +365,29 @@ export class WorkerBridgeCore {
             }
         });
     }
+    /** Request shutdown and retain ownership until this exact child exits.
+     * Does not resolve merely because SIGTERM was sent; an uncooperative child
+     * remains owned so a caller cannot start competing work prematurely.
+     */
+    async stopAndWait() {
+        const child = this.child;
+        if (!child || child.exitCode !== null || child.signalCode !== null)
+            return;
+        await new Promise((resolve) => {
+            const done = () => {
+                child.off("exit", done);
+                child.off("error", spawnFailed);
+                resolve();
+            };
+            const spawnFailed = () => {
+                if (!child.pid)
+                    done();
+            };
+            child.once("exit", done);
+            child.on("error", spawnFailed);
+            child.kill("SIGTERM");
+        });
+    }
     /** Graceful shutdown: SIGTERM the worker (no-op when none is alive). */
     kill() {
         this.log("kill", { pid: this.child?.pid });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cjhyy/code-shell-server",
-  "version": "0.9.21",
+  "version": "0.9.23",
   "description": "CodeShell server transport layer — mobile remote HTTP/WS host, pairing, passcode gate, tunnel, rooms, uploads, and session/attachment services. Electron-free; precursor of the auth gateway.",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,6 +18,14 @@
       "types": "./dist/index.worker.d.ts",
       "import": "./dist/index.worker.js"
     },
+    "./remote-relay": {
+      "types": "./dist/index.remote-relay.d.ts",
+      "import": "./dist/index.remote-relay.js"
+    },
+    "./auth": {
+      "types": "./dist/index.auth.d.ts",
+      "import": "./dist/index.auth.js"
+    },
     "./mobile-remote": {
       "types": "./dist/index.mobile-remote.d.ts",
       "import": "./dist/index.mobile-remote.js"
@@ -40,7 +48,8 @@
     }
   },
   "bin": {
-    "code-shell-serve": "./dist/bin/code-shell-serve.js"
+    "code-shell-serve": "./dist/bin/code-shell-serve.js",
+    "code-shell-settings-recovery": "./dist/bin/code-shell-settings-recovery.js"
   },
   "files": [
     "dist"
@@ -51,13 +60,13 @@
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""
   },
   "dependencies": {
-    "@cjhyy/code-shell-capability-coding": "0.9.21",
-    "@cjhyy/code-shell-core": "0.9.21",
-    "@cjhyy/code-shell-web": "0.9.21",
+    "@cjhyy/code-shell-capability-coding": "0.9.23",
+    "@cjhyy/code-shell-core": "0.9.23",
+    "@cjhyy/code-shell-web": "0.9.23",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@types/ws": "^8.18.1",
     "ws": "^8.21.0",
-    "@cjhyy/code-shell-link": "0.9.21"
+    "@cjhyy/code-shell-link": "0.9.23"
   },
   "engines": {
     "node": ">=20.10"