@ratio-app/cli 0.1.1

package/dist/lib/manifest/read-manifest.js

@@ -0,0 +1,87 @@
+// src/lib/manifest/read-manifest.ts
+import fs2 from "fs";
+import path2 from "path";
+
+// src/lib/errors.ts
+var RatioCLIError = class extends Error {
+  code;
+  exitCode;
+  hint;
+  docsUrl;
+  constructor(opts) {
+    super(opts.message);
+    this.name = new.target.name;
+    this.code = opts.code;
+    this.exitCode = opts.exitCode;
+    if (opts.hint !== void 0) this.hint = opts.hint;
+    if (opts.docsUrl !== void 0) this.docsUrl = opts.docsUrl;
+  }
+};
+var ValidationError = class extends RatioCLIError {
+  constructor(message, hint) {
+    const opts = {
+      code: "VALIDATION_ERROR",
+      exitCode: 8,
+      message
+    };
+    if (hint !== void 0) opts.hint = hint;
+    super(opts);
+  }
+};
+
+// src/lib/manifest/write-client-id.ts
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+var MANIFEST_FILE_NAME = "ratio.config.jsonc";
+
+// src/lib/manifest/read-manifest.ts
+var DEV_COMMAND_ROW = /^\s*"devCommand"\s*:\s*"([^"]*)"/m;
+var DEV_SERVER_PORT_ROW = /^\s*"devServerPort"\s*:\s*(\d+)/m;
+var DEV_SERVER_PORT_KEY = /^\s*"devServerPort"\s*:/m;
+var APP_NAME_ROW = /^\s*"appName"\s*:\s*"([^"]*)"/m;
+var CLIENT_ID_READ_ROW = /^\s*"clientId"\s*:\s*"([^"]*)"/m;
+var DEV_COMMAND_HINT = 'Add a "devCommand" entry to ratio.config.jsonc (e.g. "npm run dev") and re-run.';
+function readManifest(cwd) {
+  const filePath = path2.join(cwd, MANIFEST_FILE_NAME);
+  let content;
+  try {
+    content = fs2.readFileSync(filePath, "utf8");
+  } catch {
+    throw new ValidationError(
+      `${MANIFEST_FILE_NAME} not found in ${cwd}.`,
+      `Run this command from the app's repo root; ${MANIFEST_FILE_NAME} not found in ${cwd}.`
+    );
+  }
+  const devCommand = DEV_COMMAND_ROW.exec(content)?.[1];
+  if (devCommand === void 0 || devCommand.trim() === "") {
+    throw new ValidationError(
+      `${MANIFEST_FILE_NAME} has no usable "devCommand" entry.`,
+      DEV_COMMAND_HINT
+    );
+  }
+  let devServerPort;
+  if (DEV_SERVER_PORT_KEY.test(content)) {
+    const rawPort = DEV_SERVER_PORT_ROW.exec(content)?.[1];
+    const port = rawPort === void 0 ? Number.NaN : Number.parseInt(rawPort, 10);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      throw new ValidationError(
+        `${MANIFEST_FILE_NAME} has an invalid "devServerPort" value.`,
+        '"devServerPort" must be an unquoted integer between 1 and 65535 (e.g. "devServerPort": 3001).'
+      );
+    }
+    devServerPort = port;
+  }
+  return {
+    path: filePath,
+    devCommand,
+    devServerPort,
+    appName: APP_NAME_ROW.exec(content)?.[1],
+    clientId: CLIENT_ID_READ_ROW.exec(content)?.[1]
+  };
+}
+export {
+  DEV_COMMAND_HINT,
+  readManifest
+};
+//# sourceMappingURL=read-manifest.js.map

package/dist/lib/manifest/read-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/manifest/read-manifest.ts","../../../src/lib/errors.ts","../../../src/lib/manifest/write-client-id.ts"],"sourcesContent":["/**\n * Read-only view over the app manifest (ratio.config.jsonc).\n *\n * The file is treated as an opaque UTF-8 string: no JSON/JSONC parser is\n * involved, so comments and unknown keys are irrelevant to the read and\n * survive untouched on disk. Each field is extracted with one targeted\n * regex, mirroring the write-side idiom in write-client-id.ts. This module\n * never writes the file.\n */\n\nimport fs from 'node:fs';\nimport path from 'node:path';\nimport { ValidationError } from '../errors.js';\nimport { MANIFEST_FILE_NAME } from './write-client-id.js';\n\n/** Read-only extraction regex for the dev command line. */\nconst DEV_COMMAND_ROW = /^\\s*\"devCommand\"\\s*:\\s*\"([^\"]*)\"/m;\n\n/** Read-only extraction regex for the dev-server port (integer, unquoted). */\nconst DEV_SERVER_PORT_ROW = /^\\s*\"devServerPort\"\\s*:\\s*(\\d+)/m;\n\n/** Key-presence probe: distinguishes \"absent\" from \"present but malformed\". */\nconst DEV_SERVER_PORT_KEY = /^\\s*\"devServerPort\"\\s*:/m;\n\n/** Read-only extraction regex for the appName echo. Never used to write. */\nconst APP_NAME_ROW = /^\\s*\"appName\"\\s*:\\s*\"([^\"]*)\"/m;\n\n/** Read-only extraction regex for the clientId echo. Never used to write. */\nconst CLIENT_ID_READ_ROW = /^\\s*\"clientId\"\\s*:\\s*\"([^\"]*)\"/m;\n\n/** Hint shown whenever the dev command entry is missing or unusable. */\nexport const DEV_COMMAND_HINT =\n  'Add a \"devCommand\" entry to ratio.config.jsonc (e.g. \"npm run dev\") and re-run.';\n\nexport interface ManifestView {\n  /** Absolute path to the manifest file that was read. */\n  path: string;\n  /** The command used to start the app's own dev server. Always present. */\n  devCommand: string;\n  /** Optional local dev-server port (1-65535); undefined when absent. */\n  devServerPort: number | undefined;\n  /** Parsed from the manifest's appName row, when present. */\n  appName: string | undefined;\n  /** Parsed from the manifest's clientId row, when present. */\n  clientId: string | undefined;\n}\n\n/**\n * Locate `ratio.config.jsonc` under `cwd` and extract the fields the dev\n * orchestrator needs. Fails fast with a typed error when the file is\n * missing, when `devCommand` is absent/empty, or when `devServerPort` is\n * present but not an integer in 1-65535.\n */\nexport function readManifest(cwd: string): ManifestView {\n  const filePath = path.join(cwd, MANIFEST_FILE_NAME);\n\n  let content: string;\n  try {\n    content = fs.readFileSync(filePath, 'utf8');\n  } catch {\n    throw new ValidationError(\n      `${MANIFEST_FILE_NAME} not found in ${cwd}.`,\n      `Run this command from the app's repo root; ${MANIFEST_FILE_NAME} not found in ${cwd}.`,\n    );\n  }\n\n  const devCommand = DEV_COMMAND_ROW.exec(content)?.[1];\n  if (devCommand === undefined || devCommand.trim() === '') {\n    throw new ValidationError(\n      `${MANIFEST_FILE_NAME} has no usable \"devCommand\" entry.`,\n      DEV_COMMAND_HINT,\n    );\n  }\n\n  let devServerPort: number | undefined;\n  if (DEV_SERVER_PORT_KEY.test(content)) {\n    const rawPort = DEV_SERVER_PORT_ROW.exec(content)?.[1];\n    const port = rawPort === undefined ? Number.NaN : Number.parseInt(rawPort, 10);\n    if (!Number.isInteger(port) || port < 1 || port > 65535) {\n      throw new ValidationError(\n        `${MANIFEST_FILE_NAME} has an invalid \"devServerPort\" value.`,\n        '\"devServerPort\" must be an unquoted integer between 1 and 65535 (e.g. \"devServerPort\": 3001).',\n      );\n    }\n    devServerPort = port;\n  }\n\n  return {\n    path: filePath,\n    devCommand,\n    devServerPort,\n    appName: APP_NAME_ROW.exec(content)?.[1],\n    clientId: CLIENT_ID_READ_ROW.exec(content)?.[1],\n  };\n}\n","/**\n * Error hierarchy for the Ratio CLI. Every error thrown from a command's\n * run() is expected to be an instance of RatioCLIError so the global\n * render-error handler can map it to a deterministic stderr line and exit\n * code. Uncaught Error subclasses render as \"INTERNAL: <msg>\" with exit 1.\n *\n * No import from @oclif/core — this file is dependency-free so tests\n * can import it without oclif overhead.\n */\n\nexport class RatioCLIError extends Error {\n  readonly code: string;\n  readonly exitCode: number;\n  readonly hint?: string;\n  readonly docsUrl?: string;\n\n  constructor(opts: {\n    code: string;\n    exitCode: number;\n    message: string;\n    hint?: string;\n    docsUrl?: string;\n  }) {\n    super(opts.message);\n    this.name = new.target.name;\n    this.code = opts.code;\n    this.exitCode = opts.exitCode;\n    if (opts.hint !== undefined) this.hint = opts.hint;\n    if (opts.docsUrl !== undefined) this.docsUrl = opts.docsUrl;\n  }\n}\n\n/** Coming-soon stub UX. Renders on stdout with exit 0. */\nexport class ComingSoonError extends RatioCLIError {\n  constructor(message: string) {\n    super({ code: 'COMING_SOON', exitCode: 0, message });\n  }\n}\n\n/** User has no credentials and command requires auth. */\nexport class NotLoggedInError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Run 'ratio auth login' to sign in.\",\n  ) {\n    super({ code: 'NOT_LOGGED_IN', exitCode: 3, message, hint });\n  }\n}\n\nexport class TokenExpiredError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Run 'ratio auth login' to refresh your session.\",\n  ) {\n    super({ code: 'TOKEN_EXPIRED', exitCode: 3, message, hint });\n  }\n}\n\nexport class ScopeDeniedError extends RatioCLIError {\n  constructor(message: string, hint?: string) {\n    const opts: { code: string; exitCode: number; message: string; hint?: string } = {\n      code: 'SCOPE_DENIED',\n      exitCode: 4,\n      message,\n    };\n    if (hint !== undefined) opts.hint = hint;\n    super(opts);\n  }\n}\n\nexport class NetworkError extends RatioCLIError {\n  constructor(message: string, hint: string = 'Check your network and retry.') {\n    super({ code: 'NETWORK_ERROR', exitCode: 5, message, hint });\n  }\n}\n\nexport class RelayConnectError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Verify the tunnel URL and that the auth-server is reachable.',\n  ) {\n    super({ code: 'RELAY_CONNECT', exitCode: 6, message, hint });\n  }\n}\n\nexport class TemplateExistsError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Choose a different name or remove the existing directory.',\n  ) {\n    super({ code: 'TEMPLATE_EXISTS', exitCode: 7, message, hint });\n  }\n}\n\nexport class ValidationError extends RatioCLIError {\n  constructor(message: string, hint?: string) {\n    const opts: { code: string; exitCode: number; message: string; hint?: string } = {\n      code: 'VALIDATION_ERROR',\n      exitCode: 8,\n      message,\n    };\n    if (hint !== undefined) opts.hint = hint;\n    super(opts);\n  }\n}\n\nexport class RelayResumeGapError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Reconnect from the current cursor; older events are outside the buffer window.',\n  ) {\n    super({ code: 'RELAY_RESUME_GAP', exitCode: 9, message, hint });\n  }\n}\n\nexport class OrchestratorSpawnError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Could not start your app's dev command — check that the command in ratio.config.jsonc runs from this directory.\",\n  ) {\n    super({ code: 'ORCHESTRATOR_SPAWN', exitCode: 10, message, hint });\n  }\n}\n\nexport class OrchestratorDrainTimeoutError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Your dev command did not exit cleanly within 5 seconds — it was forcibly terminated.',\n  ) {\n    super({ code: 'ORCHESTRATOR_DRAIN', exitCode: 11, message, hint });\n  }\n}\n\nexport function isRatioCLIError(err: unknown): err is RatioCLIError {\n  return err instanceof RatioCLIError;\n}\n","/**\n * Atomically rewrite the top-level \"clientId\" value in a ratio.config.jsonc\n * file. Preserves every comment, whitespace token, and unknown key.\n *\n * The file is treated as an opaque UTF-8 string: no JSON/JSONC parser is\n * involved, so comments survive verbatim. Exactly one targeted regex is\n * applied to the `\"clientId\": \"<value>\"` line; everything else is copied\n * byte-for-byte.\n *\n * Throws ValidationError if the file is not shaped like a canonical\n * ratio.config.jsonc (no top-level \"clientId\" key on its own line).\n */\n\nimport crypto from 'node:crypto';\nimport fs from 'node:fs';\nimport path from 'node:path';\nimport { ValidationError } from '../errors.js';\n\n/** Manifest file name expected in the app repo root. */\nexport const MANIFEST_FILE_NAME = 'ratio.config.jsonc';\n\n/** Targeted single-key rewrite regex for the clientId value. */\nconst CLIENT_ID_ROW = /^(\\s*\"clientId\"\\s*:\\s*\")([^\"]*)(\"\\s*,?)/m;\n\n/** Read-only extraction regex for the appName echo. Never used to write. */\nconst APP_NAME_ROW = /^\\s*\"appName\"\\s*:\\s*\"([^\"]*)\"/m;\n\nexport interface WriteClientIdResult {\n  /** false when the file already had the same clientId. */\n  written: boolean;\n  /** Absolute path to the manifest file. */\n  path: string;\n  /** Parsed from the manifest's appName row, when present. */\n  appName?: string;\n  /** The value that was replaced, when it was non-empty and different. */\n  previousClientId?: string;\n}\n\n/**\n * Locate `ratio.config.jsonc` under `cwd`, rewrite ONLY the top-level\n * clientId value, and persist via atomic tmp+rename with 0600 discipline\n * (mirrors the credential store's write contract). Same-value re-runs are\n * a no-op (`written: false`, file untouched).\n */\nexport async function writeClientId(\n  cwd: string,\n  clientId: string,\n): Promise<WriteClientIdResult> {\n  const filePath = path.join(cwd, MANIFEST_FILE_NAME);\n\n  let content: string;\n  try {\n    content = fs.readFileSync(filePath, 'utf8');\n  } catch {\n    throw new ValidationError(\n      `${MANIFEST_FILE_NAME} not found in ${cwd}.`,\n      `Run this command from the app's repo root; ${MANIFEST_FILE_NAME} not found in ${cwd}.`,\n    );\n  }\n\n  const appNameMatch = APP_NAME_ROW.exec(content);\n  const appName = appNameMatch?.[1];\n\n  const rowMatch = CLIENT_ID_ROW.exec(content);\n  if (rowMatch === null) {\n    throw new ValidationError(\n      `${MANIFEST_FILE_NAME} has no top-level \"clientId\" entry.`,\n      'Restore the \"clientId\" line from the app template, then re-run.',\n    );\n  }\n\n  const existing = rowMatch[2] ?? '';\n\n  const base: WriteClientIdResult = {\n    written: false,\n    path: filePath,\n    ...(appName !== undefined ? { appName } : {}),\n  };\n\n  if (existing === clientId) {\n    return base;\n  }\n\n  // Function replacer: the new value is inserted verbatim, immune to `$`\n  // pattern expansion in String.replace replacement strings.\n  const updated = content.replace(\n    CLIENT_ID_ROW,\n    (_row, open: string, _old: string, close: string) =>\n      `${open}${clientId}${close}`,\n  );\n\n  const tmpPath = `${filePath}.${process.pid}.${crypto\n    .randomBytes(8)\n    .toString('hex')}.tmp`;\n  try {\n    // mode at open time closes the create-then-chmod race window.\n    fs.writeFileSync(tmpPath, updated, { mode: 0o600 });\n    fs.renameSync(tmpPath, filePath);\n  } catch (err) {\n    try {\n      fs.unlinkSync(tmpPath);\n    } catch {\n      // Best-effort cleanup: the tmp file may never have been created.\n    }\n    throw err;\n  }\n  if (process.platform !== 'win32') {\n    // Belt-and-braces: rename may preserve a prior destination mode.\n    fs.chmodSync(filePath, 0o600);\n  }\n\n  return {\n    ...base,\n    written: true,\n    ...(existing !== '' ? { previousClientId: existing } : {}),\n  };\n}\n"],"mappings":";AAUA,OAAOA,SAAQ;AACf,OAAOC,WAAU;;;ACDV,IAAM,gBAAN,cAA4B,MAAM;AAAA,EAC9B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAET,YAAY,MAMT;AACD,UAAM,KAAK,OAAO;AAClB,SAAK,OAAO,WAAW;AACvB,SAAK,OAAO,KAAK;AACjB,SAAK,WAAW,KAAK;AACrB,QAAI,KAAK,SAAS,OAAW,MAAK,OAAO,KAAK;AAC9C,QAAI,KAAK,YAAY,OAAW,MAAK,UAAU,KAAK;AAAA,EACtD;AACF;AAgEO,IAAM,kBAAN,cAA8B,cAAc;AAAA,EACjD,YAAY,SAAiB,MAAe;AAC1C,UAAM,OAA2E;AAAA,MAC/E,MAAM;AAAA,MACN,UAAU;AAAA,MACV;AAAA,IACF;AACA,QAAI,SAAS,OAAW,MAAK,OAAO;AACpC,UAAM,IAAI;AAAA,EACZ;AACF;;;AC3FA,OAAO,YAAY;AACnB,OAAO,QAAQ;AACf,OAAO,UAAU;AAIV,IAAM,qBAAqB;;;AFHlC,IAAM,kBAAkB;AAGxB,IAAM,sBAAsB;AAG5B,IAAM,sBAAsB;AAG5B,IAAM,eAAe;AAGrB,IAAM,qBAAqB;AAGpB,IAAM,mBACX;AAqBK,SAAS,aAAa,KAA2B;AACtD,QAAM,WAAWC,MAAK,KAAK,KAAK,kBAAkB;AAElD,MAAI;AACJ,MAAI;AACF,cAAUC,IAAG,aAAa,UAAU,MAAM;AAAA,EAC5C,QAAQ;AACN,UAAM,IAAI;AAAA,MACR,GAAG,kBAAkB,iBAAiB,GAAG;AAAA,MACzC,8CAA8C,kBAAkB,iBAAiB,GAAG;AAAA,IACtF;AAAA,EACF;AAEA,QAAM,aAAa,gBAAgB,KAAK,OAAO,IAAI,CAAC;AACpD,MAAI,eAAe,UAAa,WAAW,KAAK,MAAM,IAAI;AACxD,UAAM,IAAI;AAAA,MACR,GAAG,kBAAkB;AAAA,MACrB;AAAA,IACF;AAAA,EACF;AAEA,MAAI;AACJ,MAAI,oBAAoB,KAAK,OAAO,GAAG;AACrC,UAAM,UAAU,oBAAoB,KAAK,OAAO,IAAI,CAAC;AACrD,UAAM,OAAO,YAAY,SAAY,OAAO,MAAM,OAAO,SAAS,SAAS,EAAE;AAC7E,QAAI,CAAC,OAAO,UAAU,IAAI,KAAK,OAAO,KAAK,OAAO,OAAO;AACvD,YAAM,IAAI;AAAA,QACR,GAAG,kBAAkB;AAAA,QACrB;AAAA,MACF;AAAA,IACF;AACA,oBAAgB;AAAA,EAClB;AAEA,SAAO;AAAA,IACL,MAAM;AAAA,IACN;AAAA,IACA;AAAA,IACA,SAAS,aAAa,KAAK,OAAO,IAAI,CAAC;AAAA,IACvC,UAAU,mBAAmB,KAAK,OAAO,IAAI,CAAC;AAAA,EAChD;AACF;","names":["fs","path","path","fs"]}

package/dist/lib/manifest/write-client-id.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Atomically rewrite the top-level "clientId" value in a ratio.config.jsonc
+ * file. Preserves every comment, whitespace token, and unknown key.
+ *
+ * The file is treated as an opaque UTF-8 string: no JSON/JSONC parser is
+ * involved, so comments survive verbatim. Exactly one targeted regex is
+ * applied to the `"clientId": "<value>"` line; everything else is copied
+ * byte-for-byte.
+ *
+ * Throws ValidationError if the file is not shaped like a canonical
+ * ratio.config.jsonc (no top-level "clientId" key on its own line).
+ */
+/** Manifest file name expected in the app repo root. */
+declare const MANIFEST_FILE_NAME = "ratio.config.jsonc";
+interface WriteClientIdResult {
+    /** false when the file already had the same clientId. */
+    written: boolean;
+    /** Absolute path to the manifest file. */
+    path: string;
+    /** Parsed from the manifest's appName row, when present. */
+    appName?: string;
+    /** The value that was replaced, when it was non-empty and different. */
+    previousClientId?: string;
+}
+/**
+ * Locate `ratio.config.jsonc` under `cwd`, rewrite ONLY the top-level
+ * clientId value, and persist via atomic tmp+rename with 0600 discipline
+ * (mirrors the credential store's write contract). Same-value re-runs are
+ * a no-op (`written: false`, file untouched).
+ */
+declare function writeClientId(cwd: string, clientId: string): Promise<WriteClientIdResult>;
+
+export { MANIFEST_FILE_NAME, type WriteClientIdResult, writeClientId };

package/dist/lib/manifest/write-client-id.js

@@ -0,0 +1,94 @@
+// src/lib/manifest/write-client-id.ts
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+
+// src/lib/errors.ts
+var RatioCLIError = class extends Error {
+  code;
+  exitCode;
+  hint;
+  docsUrl;
+  constructor(opts) {
+    super(opts.message);
+    this.name = new.target.name;
+    this.code = opts.code;
+    this.exitCode = opts.exitCode;
+    if (opts.hint !== void 0) this.hint = opts.hint;
+    if (opts.docsUrl !== void 0) this.docsUrl = opts.docsUrl;
+  }
+};
+var ValidationError = class extends RatioCLIError {
+  constructor(message, hint) {
+    const opts = {
+      code: "VALIDATION_ERROR",
+      exitCode: 8,
+      message
+    };
+    if (hint !== void 0) opts.hint = hint;
+    super(opts);
+  }
+};
+
+// src/lib/manifest/write-client-id.ts
+var MANIFEST_FILE_NAME = "ratio.config.jsonc";
+var CLIENT_ID_ROW = /^(\s*"clientId"\s*:\s*")([^"]*)("\s*,?)/m;
+var APP_NAME_ROW = /^\s*"appName"\s*:\s*"([^"]*)"/m;
+async function writeClientId(cwd, clientId) {
+  const filePath = path.join(cwd, MANIFEST_FILE_NAME);
+  let content;
+  try {
+    content = fs.readFileSync(filePath, "utf8");
+  } catch {
+    throw new ValidationError(
+      `${MANIFEST_FILE_NAME} not found in ${cwd}.`,
+      `Run this command from the app's repo root; ${MANIFEST_FILE_NAME} not found in ${cwd}.`
+    );
+  }
+  const appNameMatch = APP_NAME_ROW.exec(content);
+  const appName = appNameMatch?.[1];
+  const rowMatch = CLIENT_ID_ROW.exec(content);
+  if (rowMatch === null) {
+    throw new ValidationError(
+      `${MANIFEST_FILE_NAME} has no top-level "clientId" entry.`,
+      'Restore the "clientId" line from the app template, then re-run.'
+    );
+  }
+  const existing = rowMatch[2] ?? "";
+  const base = {
+    written: false,
+    path: filePath,
+    ...appName !== void 0 ? { appName } : {}
+  };
+  if (existing === clientId) {
+    return base;
+  }
+  const updated = content.replace(
+    CLIENT_ID_ROW,
+    (_row, open, _old, close) => `${open}${clientId}${close}`
+  );
+  const tmpPath = `${filePath}.${process.pid}.${crypto.randomBytes(8).toString("hex")}.tmp`;
+  try {
+    fs.writeFileSync(tmpPath, updated, { mode: 384 });
+    fs.renameSync(tmpPath, filePath);
+  } catch (err) {
+    try {
+      fs.unlinkSync(tmpPath);
+    } catch {
+    }
+    throw err;
+  }
+  if (process.platform !== "win32") {
+    fs.chmodSync(filePath, 384);
+  }
+  return {
+    ...base,
+    written: true,
+    ...existing !== "" ? { previousClientId: existing } : {}
+  };
+}
+export {
+  MANIFEST_FILE_NAME,
+  writeClientId
+};
+//# sourceMappingURL=write-client-id.js.map

package/dist/lib/manifest/write-client-id.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/manifest/write-client-id.ts","../../../src/lib/errors.ts"],"sourcesContent":["/**\n * Atomically rewrite the top-level \"clientId\" value in a ratio.config.jsonc\n * file. Preserves every comment, whitespace token, and unknown key.\n *\n * The file is treated as an opaque UTF-8 string: no JSON/JSONC parser is\n * involved, so comments survive verbatim. Exactly one targeted regex is\n * applied to the `\"clientId\": \"<value>\"` line; everything else is copied\n * byte-for-byte.\n *\n * Throws ValidationError if the file is not shaped like a canonical\n * ratio.config.jsonc (no top-level \"clientId\" key on its own line).\n */\n\nimport crypto from 'node:crypto';\nimport fs from 'node:fs';\nimport path from 'node:path';\nimport { ValidationError } from '../errors.js';\n\n/** Manifest file name expected in the app repo root. */\nexport const MANIFEST_FILE_NAME = 'ratio.config.jsonc';\n\n/** Targeted single-key rewrite regex for the clientId value. */\nconst CLIENT_ID_ROW = /^(\\s*\"clientId\"\\s*:\\s*\")([^\"]*)(\"\\s*,?)/m;\n\n/** Read-only extraction regex for the appName echo. Never used to write. */\nconst APP_NAME_ROW = /^\\s*\"appName\"\\s*:\\s*\"([^\"]*)\"/m;\n\nexport interface WriteClientIdResult {\n  /** false when the file already had the same clientId. */\n  written: boolean;\n  /** Absolute path to the manifest file. */\n  path: string;\n  /** Parsed from the manifest's appName row, when present. */\n  appName?: string;\n  /** The value that was replaced, when it was non-empty and different. */\n  previousClientId?: string;\n}\n\n/**\n * Locate `ratio.config.jsonc` under `cwd`, rewrite ONLY the top-level\n * clientId value, and persist via atomic tmp+rename with 0600 discipline\n * (mirrors the credential store's write contract). Same-value re-runs are\n * a no-op (`written: false`, file untouched).\n */\nexport async function writeClientId(\n  cwd: string,\n  clientId: string,\n): Promise<WriteClientIdResult> {\n  const filePath = path.join(cwd, MANIFEST_FILE_NAME);\n\n  let content: string;\n  try {\n    content = fs.readFileSync(filePath, 'utf8');\n  } catch {\n    throw new ValidationError(\n      `${MANIFEST_FILE_NAME} not found in ${cwd}.`,\n      `Run this command from the app's repo root; ${MANIFEST_FILE_NAME} not found in ${cwd}.`,\n    );\n  }\n\n  const appNameMatch = APP_NAME_ROW.exec(content);\n  const appName = appNameMatch?.[1];\n\n  const rowMatch = CLIENT_ID_ROW.exec(content);\n  if (rowMatch === null) {\n    throw new ValidationError(\n      `${MANIFEST_FILE_NAME} has no top-level \"clientId\" entry.`,\n      'Restore the \"clientId\" line from the app template, then re-run.',\n    );\n  }\n\n  const existing = rowMatch[2] ?? '';\n\n  const base: WriteClientIdResult = {\n    written: false,\n    path: filePath,\n    ...(appName !== undefined ? { appName } : {}),\n  };\n\n  if (existing === clientId) {\n    return base;\n  }\n\n  // Function replacer: the new value is inserted verbatim, immune to `$`\n  // pattern expansion in String.replace replacement strings.\n  const updated = content.replace(\n    CLIENT_ID_ROW,\n    (_row, open: string, _old: string, close: string) =>\n      `${open}${clientId}${close}`,\n  );\n\n  const tmpPath = `${filePath}.${process.pid}.${crypto\n    .randomBytes(8)\n    .toString('hex')}.tmp`;\n  try {\n    // mode at open time closes the create-then-chmod race window.\n    fs.writeFileSync(tmpPath, updated, { mode: 0o600 });\n    fs.renameSync(tmpPath, filePath);\n  } catch (err) {\n    try {\n      fs.unlinkSync(tmpPath);\n    } catch {\n      // Best-effort cleanup: the tmp file may never have been created.\n    }\n    throw err;\n  }\n  if (process.platform !== 'win32') {\n    // Belt-and-braces: rename may preserve a prior destination mode.\n    fs.chmodSync(filePath, 0o600);\n  }\n\n  return {\n    ...base,\n    written: true,\n    ...(existing !== '' ? { previousClientId: existing } : {}),\n  };\n}\n","/**\n * Error hierarchy for the Ratio CLI. Every error thrown from a command's\n * run() is expected to be an instance of RatioCLIError so the global\n * render-error handler can map it to a deterministic stderr line and exit\n * code. Uncaught Error subclasses render as \"INTERNAL: <msg>\" with exit 1.\n *\n * No import from @oclif/core — this file is dependency-free so tests\n * can import it without oclif overhead.\n */\n\nexport class RatioCLIError extends Error {\n  readonly code: string;\n  readonly exitCode: number;\n  readonly hint?: string;\n  readonly docsUrl?: string;\n\n  constructor(opts: {\n    code: string;\n    exitCode: number;\n    message: string;\n    hint?: string;\n    docsUrl?: string;\n  }) {\n    super(opts.message);\n    this.name = new.target.name;\n    this.code = opts.code;\n    this.exitCode = opts.exitCode;\n    if (opts.hint !== undefined) this.hint = opts.hint;\n    if (opts.docsUrl !== undefined) this.docsUrl = opts.docsUrl;\n  }\n}\n\n/** Coming-soon stub UX. Renders on stdout with exit 0. */\nexport class ComingSoonError extends RatioCLIError {\n  constructor(message: string) {\n    super({ code: 'COMING_SOON', exitCode: 0, message });\n  }\n}\n\n/** User has no credentials and command requires auth. */\nexport class NotLoggedInError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Run 'ratio auth login' to sign in.\",\n  ) {\n    super({ code: 'NOT_LOGGED_IN', exitCode: 3, message, hint });\n  }\n}\n\nexport class TokenExpiredError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Run 'ratio auth login' to refresh your session.\",\n  ) {\n    super({ code: 'TOKEN_EXPIRED', exitCode: 3, message, hint });\n  }\n}\n\nexport class ScopeDeniedError extends RatioCLIError {\n  constructor(message: string, hint?: string) {\n    const opts: { code: string; exitCode: number; message: string; hint?: string } = {\n      code: 'SCOPE_DENIED',\n      exitCode: 4,\n      message,\n    };\n    if (hint !== undefined) opts.hint = hint;\n    super(opts);\n  }\n}\n\nexport class NetworkError extends RatioCLIError {\n  constructor(message: string, hint: string = 'Check your network and retry.') {\n    super({ code: 'NETWORK_ERROR', exitCode: 5, message, hint });\n  }\n}\n\nexport class RelayConnectError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Verify the tunnel URL and that the auth-server is reachable.',\n  ) {\n    super({ code: 'RELAY_CONNECT', exitCode: 6, message, hint });\n  }\n}\n\nexport class TemplateExistsError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Choose a different name or remove the existing directory.',\n  ) {\n    super({ code: 'TEMPLATE_EXISTS', exitCode: 7, message, hint });\n  }\n}\n\nexport class ValidationError extends RatioCLIError {\n  constructor(message: string, hint?: string) {\n    const opts: { code: string; exitCode: number; message: string; hint?: string } = {\n      code: 'VALIDATION_ERROR',\n      exitCode: 8,\n      message,\n    };\n    if (hint !== undefined) opts.hint = hint;\n    super(opts);\n  }\n}\n\nexport class RelayResumeGapError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Reconnect from the current cursor; older events are outside the buffer window.',\n  ) {\n    super({ code: 'RELAY_RESUME_GAP', exitCode: 9, message, hint });\n  }\n}\n\nexport class OrchestratorSpawnError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Could not start your app's dev command — check that the command in ratio.config.jsonc runs from this directory.\",\n  ) {\n    super({ code: 'ORCHESTRATOR_SPAWN', exitCode: 10, message, hint });\n  }\n}\n\nexport class OrchestratorDrainTimeoutError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Your dev command did not exit cleanly within 5 seconds — it was forcibly terminated.',\n  ) {\n    super({ code: 'ORCHESTRATOR_DRAIN', exitCode: 11, message, hint });\n  }\n}\n\nexport function isRatioCLIError(err: unknown): err is RatioCLIError {\n  return err instanceof RatioCLIError;\n}\n"],"mappings":";AAaA,OAAO,YAAY;AACnB,OAAO,QAAQ;AACf,OAAO,UAAU;;;ACLV,IAAM,gBAAN,cAA4B,MAAM;AAAA,EAC9B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAET,YAAY,MAMT;AACD,UAAM,KAAK,OAAO;AAClB,SAAK,OAAO,WAAW;AACvB,SAAK,OAAO,KAAK;AACjB,SAAK,WAAW,KAAK;AACrB,QAAI,KAAK,SAAS,OAAW,MAAK,OAAO,KAAK;AAC9C,QAAI,KAAK,YAAY,OAAW,MAAK,UAAU,KAAK;AAAA,EACtD;AACF;AAgEO,IAAM,kBAAN,cAA8B,cAAc;AAAA,EACjD,YAAY,SAAiB,MAAe;AAC1C,UAAM,OAA2E;AAAA,MAC/E,MAAM;AAAA,MACN,UAAU;AAAA,MACV;AAAA,IACF;AACA,QAAI,SAAS,OAAW,MAAK,OAAO;AACpC,UAAM,IAAI;AAAA,EACZ;AACF;;;ADrFO,IAAM,qBAAqB;AAGlC,IAAM,gBAAgB;AAGtB,IAAM,eAAe;AAmBrB,eAAsB,cACpB,KACA,UAC8B;AAC9B,QAAM,WAAW,KAAK,KAAK,KAAK,kBAAkB;AAElD,MAAI;AACJ,MAAI;AACF,cAAU,GAAG,aAAa,UAAU,MAAM;AAAA,EAC5C,QAAQ;AACN,UAAM,IAAI;AAAA,MACR,GAAG,kBAAkB,iBAAiB,GAAG;AAAA,MACzC,8CAA8C,kBAAkB,iBAAiB,GAAG;AAAA,IACtF;AAAA,EACF;AAEA,QAAM,eAAe,aAAa,KAAK,OAAO;AAC9C,QAAM,UAAU,eAAe,CAAC;AAEhC,QAAM,WAAW,cAAc,KAAK,OAAO;AAC3C,MAAI,aAAa,MAAM;AACrB,UAAM,IAAI;AAAA,MACR,GAAG,kBAAkB;AAAA,MACrB;AAAA,IACF;AAAA,EACF;AAEA,QAAM,WAAW,SAAS,CAAC,KAAK;AAEhC,QAAM,OAA4B;AAAA,IAChC,SAAS;AAAA,IACT,MAAM;AAAA,IACN,GAAI,YAAY,SAAY,EAAE,QAAQ,IAAI,CAAC;AAAA,EAC7C;AAEA,MAAI,aAAa,UAAU;AACzB,WAAO;AAAA,EACT;AAIA,QAAM,UAAU,QAAQ;AAAA,IACtB;AAAA,IACA,CAAC,MAAM,MAAc,MAAc,UACjC,GAAG,IAAI,GAAG,QAAQ,GAAG,KAAK;AAAA,EAC9B;AAEA,QAAM,UAAU,GAAG,QAAQ,IAAI,QAAQ,GAAG,IAAI,OAC3C,YAAY,CAAC,EACb,SAAS,KAAK,CAAC;AAClB,MAAI;AAEF,OAAG,cAAc,SAAS,SAAS,EAAE,MAAM,IAAM,CAAC;AAClD,OAAG,WAAW,SAAS,QAAQ;AAAA,EACjC,SAAS,KAAK;AACZ,QAAI;AACF,SAAG,WAAW,OAAO;AAAA,IACvB,QAAQ;AAAA,IAER;AACA,UAAM;AAAA,EACR;AACA,MAAI,QAAQ,aAAa,SAAS;AAEhC,OAAG,UAAU,UAAU,GAAK;AAAA,EAC9B;AAEA,SAAO;AAAA,IACL,GAAG;AAAA,IACH,SAAS;AAAA,IACT,GAAI,aAAa,KAAK,EAAE,kBAAkB,SAAS,IAAI,CAAC;AAAA,EAC1D;AACF;","names":[]}

package/dist/lib/messages.d.ts

@@ -0,0 +1,15 @@
+/**
+ * User-facing placeholder-message helpers used by every command
+ * whose real behaviour is not yet available. Kept in one module so
+ * wording stays consistent and a future edit is one place.
+ */
+/** Message for command classes registered as "Coming soon" stubs. */
+declare function comingSoonMessage(command: string): string;
+/**
+ * Message for real command surfaces whose behaviour is being built.
+ * @param command display name, e.g. 'ratio auth login'
+ * @param hint one short sentence naming what's being finalised
+ */
+declare function notYetAvailableMessage(command: string, hint: string): string;
+
+export { comingSoonMessage, notYetAvailableMessage };

package/dist/lib/messages.js

@@ -0,0 +1,16 @@
+// src/lib/messages.ts
+function comingSoonMessage(command) {
+  return `${command} \u2014 coming soon.
+This command will be available in an upcoming Ratio CLI release.
+Run 'ratio --help' after your next update to see what's new.`;
+}
+function notYetAvailableMessage(command, hint) {
+  return `${command} \u2014 not yet available.
+${hint}
+Run 'ratio --help' after your next update to see when it lands.`;
+}
+export {
+  comingSoonMessage,
+  notYetAvailableMessage
+};
+//# sourceMappingURL=messages.js.map

package/dist/lib/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/messages.ts"],"sourcesContent":["/**\n * User-facing placeholder-message helpers used by every command\n * whose real behaviour is not yet available. Kept in one module so\n * wording stays consistent and a future edit is one place.\n */\n\n/** Message for command classes registered as \"Coming soon\" stubs. */\nexport function comingSoonMessage(command: string): string {\n  return (\n    `${command} — coming soon.\\n` +\n    `This command will be available in an upcoming Ratio CLI release.\\n` +\n    `Run 'ratio --help' after your next update to see what's new.`\n  );\n}\n\n/**\n * Message for real command surfaces whose behaviour is being built.\n * @param command display name, e.g. 'ratio auth login'\n * @param hint one short sentence naming what's being finalised\n */\nexport function notYetAvailableMessage(command: string, hint: string): string {\n  return (\n    `${command} — not yet available.\\n` +\n    `${hint}\\n` +\n    `Run 'ratio --help' after your next update to see when it lands.`\n  );\n}\n"],"mappings":";AAOO,SAAS,kBAAkB,SAAyB;AACzD,SACE,GAAG,OAAO;AAAA;AAAA;AAId;AAOO,SAAS,uBAAuB,SAAiB,MAAsB;AAC5E,SACE,GAAG,OAAO;AAAA,EACP,IAAI;AAAA;AAGX;","names":[]}

package/dist/lib/orchestrator/child-runner.d.ts

@@ -0,0 +1,140 @@
+import { PreviewController } from '../preview/types.js';
+
+/**
+ * Child-process runner for `ratio app dev`.
+ *
+ * Spawns two children — the app's own dev command and the webhook
+ * listener — multiplexes their output onto stdout with per-child line
+ * prefixes, and arbitrates a single deterministic exit code out of child
+ * crashes and delivery of SIGINT/SIGTERM to the orchestrator.
+ *
+ * Everything process-shaped is injectable (spawn functions, signal
+ * source, output sinks, hard-exit) so the full lifecycle is testable
+ * without real dev servers or real signals.
+ */
+
+/** SIGTERM → SIGKILL grace window during shutdown. */
+declare const DRAIN_MS = 5000;
+/**
+ * Window within which "both children crashed" is arbitrated to the
+ * first-observed exit. The arbiter is deterministic for every ordering
+ * (first observed terminating cause always wins), which satisfies the
+ * race rule for this window and beyond.
+ */
+declare const RACE_WINDOW_MS = 200;
+/** A second interrupt inside this window forces an immediate exit (130). */
+declare const SIGNAL_FORCE_EXIT_WINDOW_MS = 2000;
+/** Per-child line-buffer bound; overflow flushes a partial line. */
+declare const CHILD_BUFFER_MAX_BYTES: number;
+/** Hint shown when the dev command cannot be tokenized safely. */
+declare const DEV_COMMAND_TOKENIZE_HINT = "devCommand must be a simple whitespace-separated command; complex shell pipelines are not supported.";
+/** Default forwarded-to port for the listener when the manifest has none. */
+declare const DEFAULT_FORWARD_PORT = 3001;
+/**
+ * Split a dev command string into an argv array: whitespace-separated,
+ * with single- or double-quoted segments kept together. Shell operators
+ * (pipes, redirects, substitutions) are rejected outright — the command
+ * is spawned without a shell, so they could never mean what the author
+ * intended.
+ */
+declare function tokenizeDevCommand(raw: string): string[];
+/**
+ * Per-stream line buffer that emits `<prefix><line>\n` only on newline
+ * boundaries, so chunks split mid-line (or mid-UTF-8-character) never
+ * corrupt the prefixed output. Bounded to CHILD_BUFFER_MAX_BYTES: on
+ * overflow, the partial line is flushed with the prefix and a newline.
+ */
+declare class LinePrefixer {
+    private readonly prefix;
+    private readonly write;
+    private buffer;
+    constructor(prefix: string, write: (chunk: string) => void);
+    push(chunk: Buffer | string): void;
+    /** Emit any buffered partial line (with prefix + newline), then reset. */
+    flush(): void;
+    private drainCompleteLines;
+}
+/** Map a child's (code, signal) exit pair to a single numeric exit code. */
+declare function exitCodeFrom(code: number | null, signal: NodeJS.Signals | null): number;
+/**
+ * Deterministic exit-code arbiter: the FIRST observed terminating cause
+ * (a child exit, or a signal delivered to the orchestrator) decides the
+ * final code. Exits observed after shutdown started are the expected
+ * result of our own SIGTERM and never change the outcome.
+ */
+declare class ExitArbiter {
+    private decidingChildCode;
+    private signalCode;
+    get shutdownInitiated(): boolean;
+    observeChildExit(code: number | null, signal: NodeJS.Signals | null): void;
+    observeSignal(sig: 'SIGINT' | 'SIGTERM'): void;
+    finalCode(): number;
+}
+/** The exact spawn options the orchestrator uses for both children. */
+interface SpawnChildOptions {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    stdio: ['ignore', 'pipe', 'pipe'];
+    shell: false;
+}
+/** Structural subset of ChildProcess the orchestrator relies on. */
+interface ChildLike {
+    readonly pid?: number | undefined;
+    readonly stdout: NodeJS.ReadableStream | null;
+    readonly stderr: NodeJS.ReadableStream | null;
+    kill(signal?: NodeJS.Signals): boolean;
+    once(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+    once(event: 'error', listener: (err: Error) => void): unknown;
+}
+type SpawnFn = (command: string, args: readonly string[], options: SpawnChildOptions) => ChildLike;
+/** Minimal process-signal surface, injectable so tests never send real signals. */
+interface SignalSource {
+    on(event: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+    removeListener(event: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+}
+/** How the listener child is invoked: always the current node executable. */
+interface ListenInvocation {
+    command: string;
+    args: string[];
+}
+/**
+ * Build the listener child's invocation. By default the listener runs as
+ * a sub-command of this same binary. The RATIO_DEV_LISTEN_BIN environment
+ * variable substitutes a different script for the listener (a test seam;
+ * unset in normal use, in which case the default binary path is used).
+ */
+declare function buildListenInvocation(env: NodeJS.ProcessEnv, devServerPort: number | undefined, argv1: string | undefined): ListenInvocation;
+interface OrchestratorIo {
+    writeOut(chunk: string): void;
+    writeErr(chunk: string): void;
+}
+interface OrchestrateOptions {
+    /** Tokenized dev command; index 0 is the executable. */
+    appArgv: string[];
+    /** Optional port hint exposed to the app child as PORT. */
+    devServerPort: number | undefined;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    preview: PreviewController;
+    verbose: boolean;
+    io: OrchestratorIo;
+    signalSource: SignalSource;
+    /** Immediate process exit for the second-interrupt fast path. */
+    hardExit: (code: number) => void;
+    /** Test seam: spawner for the app child. */
+    spawnApp?: SpawnFn;
+    /** Test seam: spawner for the listener child. */
+    spawnListen?: SpawnFn;
+    /** Test seam: shrink the SIGTERM → SIGKILL grace window. */
+    drainMs?: number;
+    /** Test seam: stand-in for the CLI's own script path. */
+    argv1?: string;
+}
+/**
+ * Run both children to completion and resolve the final exit code.
+ * Rejects with a typed error when a child cannot be spawned (exit 10) or
+ * when an otherwise-clean shutdown needed a SIGKILL escalation (exit 11).
+ */
+declare function orchestrate(options: OrchestrateOptions): Promise<number>;
+
+export { CHILD_BUFFER_MAX_BYTES, type ChildLike, DEFAULT_FORWARD_PORT, DEV_COMMAND_TOKENIZE_HINT, DRAIN_MS, ExitArbiter, LinePrefixer, type ListenInvocation, type OrchestrateOptions, type OrchestratorIo, RACE_WINDOW_MS, SIGNAL_FORCE_EXIT_WINDOW_MS, type SignalSource, type SpawnChildOptions, type SpawnFn, buildListenInvocation, exitCodeFrom, orchestrate, tokenizeDevCommand };