@mutates/cli 2.1.0

package/README.md

@@ -0,0 +1,105 @@
+# @mutates/cli
+
+AST mutation CLI for AI agents. `mutates` is a thin client over
+`@mutates/core`; a per-project daemon owns a single `ts-morph` `Project`,
+mints opaque `@nN` node refs, applies structural edits in memory, and
+saves with mtime+size conflict detection.
+
+## Install
+
+```sh
+npm i -g @mutates/cli
+```
+
+This puts a `mutates` binary on your `PATH`. No project-local install is
+required; the CLI operates against the current working directory by
+default, or against an explicit project root via `--root <path>`.
+
+## The loop: snapshot → act → save
+
+Every interaction follows the same three steps. Snapshots mint refs;
+acts (mutation ops) invalidate those refs; saving flushes to disk if no
+on-disk file has changed since the daemon loaded it.
+
+```sh
+# 1. Snapshot a file to discover its top-level shape and mint refs.
+mutates snapshot src/app.ts
+
+#    Output (text mode):
+#      @n1  ImportDeclaration  from 'fastify'
+#      @n2  ClassDeclaration   AppController  [exported]
+#      @n3  FunctionDeclaration bootstrap     [exported, async]
+
+# 2. Act. Pass the structure payload as JSON.
+mutates add-methods --target @n2 \
+  --json '{"name":"ping","returnType":"string","statements":["return \"pong\";"]}'
+
+# 3. Inspect what changed.
+mutates diff
+
+# 4. Save (or `--dry-run` first to preview the write set).
+mutates save
+```
+
+Every command honours `--json` for machine-readable output. Errors land
+on stderr as JSON `{ code, message, details }`; the exit code maps to
+the error category (`STALE_REF` → 5, `STALE_FILE` → 6, etc.). See
+`mutates schema` and `mutates skills get core` for the full surface.
+
+### Sessions
+
+A daemon spawns automatically on the first command for a given root and
+shuts itself down after 10 minutes of idle (`MUTATES_IDLE_TIMEOUT=<ms>`
+to override). Explicit lifecycle commands exist too:
+
+```sh
+mutates open                      # eager spawn
+mutates sessions list             # daemons for cwd
+mutates sessions list --all       # every live daemon on this host
+mutates close --all               # stop everything
+```
+
+### Staleness
+
+- `STALE_REF` — a ref was invalidated by a mutation; re-snapshot the
+  file and try again.
+- `STALE_FILE` — a file on disk changed since the daemon loaded it; run
+  `mutates reload <file>` (which drops in-memory edits for that file)
+  or close the session and start over.
+
+## Discovering ops
+
+`mutates schema` returns the JSON Schema for every generated operation
+— `add-classes`, `edit-methods`, `remove-decorators`, … — covering every
+exported `add* / edit* / remove* / get*` function on `@mutates/core`.
+
+```sh
+mutates schema                    # full manifest, every op
+mutates schema add-classes        # one op's payload shape
+mutates --help                    # tree of commands
+```
+
+## Agent guide
+
+`mutates skills get core` returns a single Markdown document that walks
+an agent through the snapshot → act → save loop, common patterns, and
+the full troubleshooting tree for `STALE_REF` / `STALE_FILE`. It is the
+canonical starting point when wiring `mutates` into a new agent
+runtime.
+
+```sh
+mutates skills list
+mutates skills get core
+```
+
+## Multi-session
+
+Multiple project roots run independent daemons. Every command except
+`open`, `close --all`, `sessions list`, and `skills *` accepts
+`--session <id>` to target a specific session; the default is the
+session bound to the project root resolved from `--root` / cwd
+(Req 10.1, 10.2).
+
+## License
+
+Apache-2.0. See [LICENSE](../../LICENSE).

package/bin/mutates.d.ts

@@ -0,0 +1 @@
+export declare const main: import("citty").CommandDef<import("citty").ArgsDef>;

package/bin/mutates.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = void 0;
+const tslib_1 = require("tslib");
+const citty_1 = require("citty");
+const package_json_1 = tslib_1.__importDefault(require("../package.json"));
+const open_1 = tslib_1.__importDefault(require("../src/commands/core/open"));
+const generated_1 = require("../src/commands/generated");
+exports.main = (0, citty_1.defineCommand)({
+    meta: {
+        name: 'mutates',
+        version: package_json_1.default.version,
+        description: 'AST mutation CLI for AI agents',
+    },
+    subCommands: {
+        open: open_1.default,
+        close: () => Promise.resolve().then(() => tslib_1.__importStar(require('../src/commands/core/close'))).then((m) => m.default),
+        sessions: () => Promise.resolve().then(() => tslib_1.__importStar(require('../src/commands/core/sessions'))).then((m) => m.default),
+        snapshot: () => Promise.resolve().then(() => tslib_1.__importStar(require('../src/commands/core/snapshot'))).then((m) => m.default),
+        find: () => Promise.resolve().then(() => tslib_1.__importStar(require('../src/commands/core/find'))).then((m) => m.default),
+        diff: () => Promise.resolve().then(() => tslib_1.__importStar(require('../src/commands/core/diff'))).then((m) => m.default),
+        save: () => Promise.resolve().then(() => tslib_1.__importStar(require('../src/commands/core/save'))).then((m) => m.default),
+        reload: () => Promise.resolve().then(() => tslib_1.__importStar(require('../src/commands/core/reload'))).then((m) => m.default),
+        'list-files': () => Promise.resolve().then(() => tslib_1.__importStar(require('../src/commands/core/list-files'))).then((m) => m.default),
+        schema: () => Promise.resolve().then(() => tslib_1.__importStar(require('../src/commands/core/schema'))).then((m) => m.default),
+        skills: () => Promise.resolve().then(() => tslib_1.__importStar(require('../src/commands/core/skills'))).then((m) => m.default),
+        ...generated_1.GENERATED_COMMANDS,
+    },
+    run() {
+        // eslint-disable-next-line no-console
+        console.log('Run `mutates --help` to see available commands.');
+    },
+});
+if (require.main === module) {
+    (0, citty_1.runMain)(exports.main);
+}
+//# sourceMappingURL=mutates.js.map

package/bin/mutates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutates.js","sourceRoot":"","sources":["../../../../packages/cli/bin/mutates.ts"],"names":[],"mappings":";;;;AAAA,iCAA+C;AAE/C,2EAAkC;AAClC,6EAA6C;AAC7C,yDAA+D;AAElD,QAAA,IAAI,GAAG,IAAA,qBAAa,EAAC;IAChC,IAAI,EAAE;QACJ,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,sBAAG,CAAC,OAAO;QACpB,WAAW,EAAE,gCAAgC;KAC9C;IACD,WAAW,EAAE;QACX,IAAI,EAAJ,cAAI;QACJ,KAAK,EAAE,GAAG,EAAE,CAAC,0DAAO,4BAA4B,IAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;QACxE,QAAQ,EAAE,GAAG,EAAE,CAAC,0DAAO,+BAA+B,IAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;QAC9E,QAAQ,EAAE,GAAG,EAAE,CAAC,0DAAO,+BAA+B,IAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;QAC9E,IAAI,EAAE,GAAG,EAAE,CAAC,0DAAO,2BAA2B,IAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;QACtE,IAAI,EAAE,GAAG,EAAE,CAAC,0DAAO,2BAA2B,IAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;QACtE,IAAI,EAAE,GAAG,EAAE,CAAC,0DAAO,2BAA2B,IAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;QACtE,MAAM,EAAE,GAAG,EAAE,CAAC,0DAAO,6BAA6B,IAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;QAC1E,YAAY,EAAE,GAAG,EAAE,CAAC,0DAAO,iCAAiC,IAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;QACpF,MAAM,EAAE,GAAG,EAAE,CAAC,0DAAO,6BAA6B,IAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;QAC1E,MAAM,EAAE,GAAG,EAAE,CAAC,0DAAO,6BAA6B,IAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;QAC1E,GAAG,8BAAkB;KACtB;IACD,GAAG;QACD,sCAAsC;QACtC,OAAO,CAAC,GAAG,CAAC,iDAAiD,CAAC,CAAC;IACjE,CAAC;CACF,CAAC,CAAC;AAEH,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;IAC5B,IAAA,eAAO,EAAC,YAAI,CAAC,CAAC;AAChB,CAAC"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@mutates/cli",
+  "version": "2.1.0",
+  "keywords": [
+    "ast",
+    "cli",
+    "typescript",
+    "mutations"
+  ],
+  "homepage": "https://github.com/IKatsuba/mutates",
+  "repository": "https://github.com/IKatsuba/mutates",
+  "license": "Apache-2.0",
+  "contributors": [
+    "Igor Katsuba <igor@katsuba.dev>"
+  ],
+  "type": "commonjs",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./bin/mutates": "./bin/mutates.js",
+    "./daemon/entry": "./src/daemon/entry.js"
+  },
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "typings": "./src/index.d.ts",
+  "bin": {
+    "mutates": "./bin/mutates.js"
+  },
+  "dependencies": {
+    "@mutates/core": "2.1.0",
+    "ajv": "^8.17.1",
+    "citty": "^0.1.6",
+    "diff": "^4.0.2",
+    "tslib": "^2.3.0",
+    "xxhash-wasm": "^1.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "authors": [
+    "Igor Katsuba <igor@katsuba.dev>"
+  ]
+}

package/src/client/format-snapshot.d.ts

@@ -0,0 +1,13 @@
+import type { SnapshotResult } from '../session/snapshot';
+/**
+ * Render a {@link SnapshotResult} as the human-readable text shown in
+ * design.md (see the "Snapshot rendering" example).
+ *
+ * Example output:
+ *
+ *   File: src/app.ts
+ *   @n1 [import] from "rxjs"
+ *   @n2 [class] AppService exported
+ *   @n3 [function] helper exported
+ */
+export declare function formatSnapshot(snapshot: SnapshotResult): string;

package/src/client/format-snapshot.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatSnapshot = formatSnapshot;
+/**
+ * Render a {@link SnapshotResult} as the human-readable text shown in
+ * design.md (see the "Snapshot rendering" example).
+ *
+ * Example output:
+ *
+ *   File: src/app.ts
+ *   @n1 [import] from "rxjs"
+ *   @n2 [class] AppService exported
+ *   @n3 [function] helper exported
+ */
+function formatSnapshot(snapshot) {
+    const lines = [`File: ${snapshot.file}`];
+    for (const entry of snapshot.entries) {
+        lines.push(formatEntry(entry));
+    }
+    return lines.join('\n') + '\n';
+}
+function formatEntry(entry) {
+    const parts = [`${entry.ref} [${entry.kind}]`];
+    if (entry.kind === 'import' && entry.name) {
+        parts.push(`from ${JSON.stringify(entry.name)}`);
+    }
+    else if (entry.name) {
+        parts.push(entry.name);
+    }
+    if (entry.modifiers && entry.modifiers.length > 0) {
+        parts.push(entry.modifiers.join(' '));
+    }
+    if (entry.children !== undefined && entry.children > 0) {
+        parts.push(`(${entry.children} children)`);
+    }
+    return parts.join(' ');
+}
+//# sourceMappingURL=format-snapshot.js.map

package/src/client/format-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-snapshot.js","sourceRoot":"","sources":["../../../../../packages/cli/src/client/format-snapshot.ts"],"names":[],"mappings":";;AAaA,wCAMC;AAjBD;;;;;;;;;;GAUG;AACH,SAAgB,cAAc,CAAC,QAAwB;IACrD,MAAM,KAAK,GAAa,CAAC,SAAS,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACnD,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;QACrC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AACjC,CAAC;AAED,SAAS,WAAW,CAAC,KAAoB;IACvC,MAAM,KAAK,GAAa,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC;IACzD,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;QAC1C,KAAK,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACnD,CAAC;SAAM,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IACD,IAAI,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACxC,CAAC;IACD,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;QACvD,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,QAAQ,YAAY,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC"}

package/src/client/output.d.ts

@@ -0,0 +1,25 @@
+import { RpcError } from '../proto/jsonrpc';
+export interface ErrorPayload {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+/** Convert an `RpcError` into the surface payload required by Req 8.3. */
+export declare function errorPayload(err: RpcError): ErrorPayload;
+/** Map an error's symbolic name to its CLI exit code. */
+export declare function exitCodeFor(err: RpcError): number;
+/**
+ * Render an error to stderr as JSON (one line, machine-parseable). The
+ * caller is responsible for `process.exit(exitCodeFor(err))` afterwards.
+ *
+ * Non-`RpcError` throws are wrapped as `INTERNAL_ERROR` so the CLI
+ * always emits the documented shape.
+ */
+export declare function renderError(err: unknown, stream?: NodeJS.WritableStream): void;
+/**
+ * Render a result to stdout. `text` format uses a human-friendly
+ * stringification (`String(result)` for primitives, `JSON.stringify`
+ * with indent for objects); `json` always uses single-line JSON for
+ * pipe-friendliness.
+ */
+export declare function renderResult(result: unknown, format?: 'text' | 'json', stream?: NodeJS.WritableStream): void;

package/src/client/output.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.errorPayload = errorPayload;
+exports.exitCodeFor = exitCodeFor;
+exports.renderError = renderError;
+exports.renderResult = renderResult;
+const error_codes_1 = require("../proto/error-codes");
+const jsonrpc_1 = require("../proto/jsonrpc");
+/**
+ * CLI exit codes per design.md §Error Handling. Keep in sync with the
+ * symbolic-name surface; `INTERNAL_ERROR` defaults to 1 like a generic
+ * unhandled failure.
+ */
+const EXIT_CODE_BY_SYMBOLIC = {
+    INTERNAL_ERROR: 1,
+    INVALID_INPUT: 2,
+    NOT_FOUND: 3,
+    SESSION_NOT_FOUND: 4,
+    STALE_REF: 5,
+    STALE_FILE: 6,
+    IO_ERROR: 7,
+};
+/** Convert an `RpcError` into the surface payload required by Req 8.3. */
+function errorPayload(err) {
+    const payload = {
+        code: (0, error_codes_1.toSymbolic)(err.code),
+        message: err.message,
+    };
+    if (err.data !== undefined)
+        payload.details = err.data;
+    return payload;
+}
+/** Map an error's symbolic name to its CLI exit code. */
+function exitCodeFor(err) {
+    const symbolic = (0, error_codes_1.toSymbolic)(err.code);
+    return EXIT_CODE_BY_SYMBOLIC[symbolic] ?? 1;
+}
+/**
+ * Render an error to stderr as JSON (one line, machine-parseable). The
+ * caller is responsible for `process.exit(exitCodeFor(err))` afterwards.
+ *
+ * Non-`RpcError` throws are wrapped as `INTERNAL_ERROR` so the CLI
+ * always emits the documented shape.
+ */
+function renderError(err, stream = process.stderr) {
+    const rpcErr = err instanceof jsonrpc_1.RpcError
+        ? err
+        : new jsonrpc_1.RpcError(error_codes_1.ErrorCode.InternalError, err instanceof Error ? err.message : String(err));
+    stream.write(JSON.stringify(errorPayload(rpcErr)) + '\n');
+}
+/**
+ * Render a result to stdout. `text` format uses a human-friendly
+ * stringification (`String(result)` for primitives, `JSON.stringify`
+ * with indent for objects); `json` always uses single-line JSON for
+ * pipe-friendliness.
+ */
+function renderResult(result, format = 'text', stream = process.stdout) {
+    if (format === 'json') {
+        stream.write(JSON.stringify(result) + '\n');
+        return;
+    }
+    if (result === undefined || result === null) {
+        stream.write('\n');
+        return;
+    }
+    if (typeof result === 'string') {
+        stream.write(result.endsWith('\n') ? result : result + '\n');
+        return;
+    }
+    if (typeof result === 'number' || typeof result === 'boolean') {
+        stream.write(String(result) + '\n');
+        return;
+    }
+    stream.write(JSON.stringify(result, null, 2) + '\n');
+}
+//# sourceMappingURL=output.js.map

package/src/client/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../../../../packages/cli/src/client/output.ts"],"names":[],"mappings":";;AAyBA,oCAOC;AAGD,kCAGC;AASD,kCAMC;AAQD,oCAsBC;AAnFD,sDAA6D;AAC7D,8CAA4C;AAE5C;;;;GAIG;AACH,MAAM,qBAAqB,GAA2B;IACpD,cAAc,EAAE,CAAC;IACjB,aAAa,EAAE,CAAC;IAChB,SAAS,EAAE,CAAC;IACZ,iBAAiB,EAAE,CAAC;IACpB,SAAS,EAAE,CAAC;IACZ,UAAU,EAAE,CAAC;IACb,QAAQ,EAAE,CAAC;CACZ,CAAC;AAQF,0EAA0E;AAC1E,SAAgB,YAAY,CAAC,GAAa;IACxC,MAAM,OAAO,GAAiB;QAC5B,IAAI,EAAE,IAAA,wBAAU,EAAC,GAAG,CAAC,IAAI,CAAC;QAC1B,OAAO,EAAE,GAAG,CAAC,OAAO;KACrB,CAAC;IACF,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,CAAC,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC;IACvD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,yDAAyD;AACzD,SAAgB,WAAW,CAAC,GAAa;IACvC,MAAM,QAAQ,GAAG,IAAA,wBAAU,EAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACtC,OAAO,qBAAqB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,WAAW,CAAC,GAAY,EAAE,SAAgC,OAAO,CAAC,MAAM;IACtF,MAAM,MAAM,GACV,GAAG,YAAY,kBAAQ;QACrB,CAAC,CAAC,GAAG;QACL,CAAC,CAAC,IAAI,kBAAQ,CAAC,uBAAS,CAAC,aAAa,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9F,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;GAKG;AACH,SAAgB,YAAY,CAC1B,MAAe,EACf,SAA0B,MAAM,EAChC,SAAgC,OAAO,CAAC,MAAM;IAE9C,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;QAC5C,OAAO;IACT,CAAC;IACD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QAC5C,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACnB,OAAO;IACT,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;QAC7D,OAAO;IACT,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,OAAO,MAAM,KAAK,SAAS,EAAE,CAAC;QAC9D,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;QACpC,OAAO;IACT,CAAC;IACD,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AACvD,CAAC"}

package/src/client/rpc-client-testing.d.ts

@@ -0,0 +1,12 @@
+import { type DaemonHandle } from '../daemon/entry';
+/**
+ * Spin up an in-process daemon listening on a fresh temp socket for use
+ * by client integration tests. Returns the daemon handle plus the socket
+ * path so callers can clean up.
+ *
+ * This is test-only; do not export from the public package entrypoint.
+ */
+export declare function startDaemonAndConnect(projectRoot: string): Promise<{
+    daemon: DaemonHandle;
+    sockPath: string;
+}>;

package/src/client/rpc-client-testing.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startDaemonAndConnect = startDaemonAndConnect;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const entry_1 = require("../daemon/entry");
+/**
+ * Spin up an in-process daemon listening on a fresh temp socket for use
+ * by client integration tests. Returns the daemon handle plus the socket
+ * path so callers can clean up.
+ *
+ * This is test-only; do not export from the public package entrypoint.
+ */
+async function startDaemonAndConnect(projectRoot) {
+    const sockDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'mutates-sock-'));
+    const sockPath = (0, node_path_1.join)(sockDir, 'd.sock');
+    const daemon = await (0, entry_1.startDaemon)({ root: projectRoot, sock: sockPath });
+    return { daemon, sockPath };
+}
+//# sourceMappingURL=rpc-client-testing.js.map

package/src/client/rpc-client-testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-client-testing.js","sourceRoot":"","sources":["../../../../../packages/cli/src/client/rpc-client-testing.ts"],"names":[],"mappings":";;AAaA,sDAOC;AApBD,qCAAsC;AACtC,qCAAiC;AACjC,yCAAiC;AAEjC,2CAAiE;AAEjE;;;;;;GAMG;AACI,KAAK,UAAU,qBAAqB,CACzC,WAAmB;IAEnB,MAAM,OAAO,GAAG,IAAA,qBAAW,EAAC,IAAA,gBAAI,EAAC,IAAA,gBAAM,GAAE,EAAE,eAAe,CAAC,CAAC,CAAC;IAC7D,MAAM,QAAQ,GAAG,IAAA,gBAAI,EAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,MAAM,IAAA,mBAAW,EAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;IACxE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAC9B,CAAC"}

package/src/client/rpc-client.d.ts

@@ -0,0 +1,35 @@
+export interface ConnectOptions {
+    /** Absolute or relative project root. */
+    root: string;
+    /** Optional pre-existing session id to validate via `session.list`. */
+    sessionId?: string;
+    /** Override the daemon entry path. Used by integration tests. */
+    daemonEntry?: string;
+    /** Override the Node executable used to spawn the daemon. */
+    node?: string;
+}
+export interface Connection {
+    call<R = unknown>(method: string, params?: unknown): Promise<R>;
+    close(): Promise<void>;
+}
+/**
+ * Derive a per-root socket path. Unix uses a 32-hex suffix under
+ * `os.tmpdir()`; Windows uses a named pipe with the same hash. The
+ * caller passes the chosen path to `--sock`, ensuring the daemon and
+ * the client agree.
+ */
+export declare function deriveSocketPath(root: string): string;
+/**
+ * Discover or spawn a daemon for `root`, perform the handshake, return a
+ * {@link Connection} for further calls.
+ *
+ * Discovery rules (see design.md §RpcClient):
+ *  1. Read the lockfile. If present and `process.kill(pid, 0)` succeeds,
+ *     connect to its `sock`.
+ *  2. On lockfile miss or stale (read returns null) — unlink any stale
+ *     lockfile, spawn `node <entry> --root <root> --sock <derived>`
+ *     detached, poll for the socket up to 2 s.
+ *  3. After connect: if `sessionId` is supplied, call `session.list` and
+ *     ensure it appears; else call `session.open { root }`.
+ */
+export declare function connectClient(opts: ConnectOptions): Promise<Connection>;

package/src/client/rpc-client.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveSocketPath = deriveSocketPath;
+exports.connectClient = connectClient;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_net_1 = require("node:net");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const lockfile_1 = require("../discovery/lockfile");
+const error_codes_1 = require("../proto/error-codes");
+const jsonrpc_1 = require("../proto/jsonrpc");
+const SPAWN_TIMEOUT_MS = 2_000;
+const SPAWN_POLL_MS = 50;
+/**
+ * Default daemon entry path resolved from this module's compiled location.
+ * Production: `dist/packages/cli/src/daemon/entry.js`. Tests typically
+ * pass an explicit path via {@link ConnectOptions.daemonEntry}.
+ */
+function defaultDaemonEntry() {
+    // The compiled JS sits next to this file at runtime (./client/rpc-client.js).
+    // The daemon entry compiles to ../daemon/entry.js.
+    return (0, node_path_1.join)(__dirname, '..', 'daemon', 'entry.js');
+}
+/**
+ * Derive a per-root socket path. Unix uses a 32-hex suffix under
+ * `os.tmpdir()`; Windows uses a named pipe with the same hash. The
+ * caller passes the chosen path to `--sock`, ensuring the daemon and
+ * the client agree.
+ */
+function deriveSocketPath(root) {
+    const abs = (0, node_path_1.resolve)(root);
+    const hash = (0, node_crypto_1.createHash)('sha256').update(abs).digest('hex').slice(0, 16);
+    if (process.platform === 'win32') {
+        return `\\\\.\\pipe\\mutates-${hash}`;
+    }
+    return (0, node_path_1.join)((0, node_os_1.tmpdir)(), `mutates-${hash}.sock`);
+}
+/**
+ * Discover or spawn a daemon for `root`, perform the handshake, return a
+ * {@link Connection} for further calls.
+ *
+ * Discovery rules (see design.md §RpcClient):
+ *  1. Read the lockfile. If present and `process.kill(pid, 0)` succeeds,
+ *     connect to its `sock`.
+ *  2. On lockfile miss or stale (read returns null) — unlink any stale
+ *     lockfile, spawn `node <entry> --root <root> --sock <derived>`
+ *     detached, poll for the socket up to 2 s.
+ *  3. After connect: if `sessionId` is supplied, call `session.list` and
+ *     ensure it appears; else call `session.open { root }`.
+ */
+async function connectClient(opts) {
+    const absRoot = (0, node_path_1.resolve)(opts.root);
+    let lock = (0, lockfile_1.read)(absRoot);
+    if (!lock) {
+        // Clear any stale entry left by a crashed daemon.
+        (0, lockfile_1.unlink)(absRoot);
+        const sock = deriveSocketPath(absRoot);
+        spawnDaemon(absRoot, sock, opts);
+        lock = await waitForLockfile(absRoot);
+    }
+    const connection = await openSocketConnection(lock.sock);
+    if (opts.sessionId) {
+        const sessions = await connection.call('session.list', {});
+        const exists = sessions.some((s) => s.id === opts.sessionId);
+        if (!exists) {
+            await connection.close();
+            throw new jsonrpc_1.RpcError(error_codes_1.ErrorCode.SessionNotFound, `session not found: ${opts.sessionId}`, {
+                sessionId: opts.sessionId,
+            });
+        }
+    }
+    return connection;
+}
+function spawnDaemon(root, sock, opts) {
+    const entry = opts.daemonEntry ?? defaultDaemonEntry();
+    const node = opts.node ?? process.execPath;
+    if (!(0, node_fs_1.existsSync)(entry)) {
+        throw new Error(`mutates daemon entry not found at ${entry}`);
+    }
+    const child = (0, node_child_process_1.spawn)(node, [entry, '--root', root, '--sock', sock], {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+    });
+    child.unref();
+}
+async function waitForLockfile(root) {
+    const deadline = Date.now() + SPAWN_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        const lock = (0, lockfile_1.read)(root);
+        if (lock && (0, node_fs_1.existsSync)((0, lockfile_1.lockfilePath)(root)))
+            return lock;
+        await sleep(SPAWN_POLL_MS);
+    }
+    throw new Error(`mutates daemon did not start within ${SPAWN_TIMEOUT_MS}ms`);
+}
+function sleep(ms) {
+    return new Promise((res) => setTimeout(res, ms));
+}
+function openSocketConnection(sock) {
+    return new Promise((resolveConn, rejectConn) => {
+        const codec = new jsonrpc_1.NdjsonCodec();
+        const socket = (0, node_net_1.connect)(sock);
+        const internals = {
+            socket,
+            pending: new Map(),
+            codec,
+            nextId: 1,
+        };
+        const decoder = codec.decode();
+        socket.pipe(decoder);
+        decoder.on('data', (msg) => {
+            const id = msg.id;
+            if (id === null || id === undefined)
+                return;
+            const resolver = internals.pending.get(id);
+            if (resolver) {
+                internals.pending.delete(id);
+                resolver(msg);
+            }
+        });
+        const failPending = (err) => {
+            for (const [, resolver] of internals.pending) {
+                // resolver expects an RpcResponse; synthesize an error response.
+                resolver({
+                    jsonrpc: '2.0',
+                    id: null,
+                    error: { code: error_codes_1.ErrorCode.IoError, message: err.message },
+                });
+            }
+            internals.pending.clear();
+        };
+        socket.on('error', (err) => {
+            failPending(err);
+            rejectConn(err);
+        });
+        socket.on('close', () => failPending(new Error('socket closed')));
+        socket.once('connect', () => {
+            const conn = {
+                async call(method, params) {
+                    const id = internals.nextId++;
+                    const frame = {
+                        jsonrpc: '2.0',
+                        id,
+                        method,
+                        params: params ?? {},
+                    };
+                    return new Promise((resolveCall, rejectCall) => {
+                        internals.pending.set(id, (msg) => {
+                            if ('error' in msg) {
+                                rejectCall(new jsonrpc_1.RpcError(msg.error.code, msg.error.message, msg.error.data));
+                            }
+                            else {
+                                resolveCall(msg.result);
+                            }
+                        });
+                        socket.write(codec.encode(frame));
+                    });
+                },
+                close() {
+                    return new Promise((res) => {
+                        socket.end(() => res());
+                    });
+                },
+            };
+            resolveConn(conn);
+        });
+    });
+}
+//# sourceMappingURL=rpc-client.js.map

package/src/client/rpc-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-client.js","sourceRoot":"","sources":["../../../../../packages/cli/src/client/rpc-client.ts"],"names":[],"mappings":"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"}

package/src/commands/core/close.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `mutates close` — close a session by id, or close every live session
+ * for this project root when `--all` is set.
+ *
+ * When neither `--session` nor `--all` is supplied, the command exits
+ * with an INVALID_INPUT-shaped error payload.
+ */
+declare const _default: import("citty").CommandDef<{
+    session: {
+        type: "string";
+        description: string;
+    };
+    all: {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
+    root: {
+        type: "string";
+        description: string;
+    };
+    json: {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
+}>;
+export default _default;