@catalyst-cloud/cli 0.8.0

package/skills/whats-happening/scripts/lib/cli.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: spawn the catalyst-skills CLI.
+// The CLI holds the SDK and the key; this file holds neither. It reads customer.json only
+// to learn where the CLI lives, and it exits 2 with one line when the machine is not connected.
+// Run any script beside this one with --help; this file is a library and is never run directly.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
+
+export const PACKAGE = "@catalyst-cloud/catalyst-skills";
+export const NOT_CONFIGURED_EXIT = 2;
+
+export function configPath() {
+  const home = process.env.CATALYST_SKILLS_HOME ?? process.env.HOME ?? "/";
+  return join(home, ".config", "catalyst-cloud", "customer.json");
+}
+
+/** The connected-machine config, or exit 2 with the one line that says how to connect. */
+export function loadConfig() {
+  const path = configPath();
+  if (!existsSync(path)) notConfigured(`no config at ${path}`);
+  try {
+    const cfg = JSON.parse(readFileSync(path, "utf8"));
+    if (!hasCredential(cfg)) notConfigured(`config at ${path} has no key or login`);
+    return cfg;
+  } catch (err) {
+    if (err && err.exitCode === NOT_CONFIGURED_EXIT) throw err;
+    notConfigured(`config at ${path} is unreadable`);
+  }
+}
+
+function notConfigured(why) {
+  process.stderr.write(`not connected (${why}) — run: ${CONNECT_COMMAND}\n`);
+  process.exit(NOT_CONFIGURED_EXIT);
+}
+
+/**
+ * Run one catalyst-skills verb and return {code, stdout, stderr}. Uses the CLI path the login
+ * recorded when it still exists, else `npx <package>`. A CLI exit of 2 with a "not joined" or
+ * "not connected" line is turned into this script's own exit 2, so every caller sees one contract.
+ */
+export function runCli(args, opts = {}) {
+  const cfg = loadConfig();
+  const useRecorded = typeof cfg.cliPath === "string" && existsSync(cfg.cliPath);
+  const cmd = useRecorded ? process.execPath : "npx";
+  const argv = useRecorded ? [cfg.cliPath, ...args] : [PACKAGE, ...args];
+  const res = spawnSync(cmd, argv, {
+    input: opts.stdin,
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+    shell: !useRecorded && process.platform === "win32",
+    env: process.env,
+  });
+  if (res.error) {
+    process.stderr.write(`could not run ${cmd}: ${res.error.message}\n`);
+    process.exit(NOT_CONFIGURED_EXIT);
+  }
+  const stdout = res.stdout ?? "";
+  const stderr = res.stderr ?? "";
+  if (res.status === NOT_CONFIGURED_EXIT && /not (joined|connected|configured)/i.test(stderr)) {
+    process.stderr.write(stderr);
+    process.exit(NOT_CONFIGURED_EXIT);
+  }
+  return { code: res.status ?? 1, stdout, stderr };
+}
+
+/** Run a verb and require success; on failure print the CLI's own stderr and exit with its code (or 1). */
+export function mustRun(args, opts = {}) {
+  const r = runCli(args, opts);
+  if (r.code !== 0) {
+    if (r.stderr) process.stderr.write(r.stderr.endsWith("\n") ? r.stderr : `${r.stderr}\n`);
+    if (r.stdout && !opts.quiet) process.stdout.write(r.stdout.endsWith("\n") ? r.stdout : `${r.stdout}\n`);
+    process.exit(r.code === 0 ? 1 : r.code);
+  }
+  return r;
+}
+
+/** Parse the CLI's --json stdout; a non-JSON answer is a failed check, exit 1. */
+export function parseJson(stdout, what = "output") {
+  try {
+    return JSON.parse(stdout.trim());
+  } catch {
+    process.stderr.write(`could not parse ${what} as JSON: ${stdout.trim().slice(0, 200)}\n`);
+    process.exit(1);
+  }
+}
+
+/** Minimal flag parsing for the scripts: --name value, --name=value, --flag, repeated flags collect. */
+export function parseFlags(argv, spec) {
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") return { help: true, flags, positionals };
+    if (a.startsWith("--")) {
+      let name = a.slice(2);
+      let value;
+      const eq = name.indexOf("=");
+      if (eq !== -1) {
+        value = name.slice(eq + 1);
+        name = name.slice(0, eq);
+      }
+      const s = spec[name];
+      if (!s) {
+        process.stderr.write(`unknown option --${name} (try --help)\n`);
+        process.exit(1);
+      }
+      if (s.value) {
+        if (value === undefined) value = argv[++i];
+        if (value === undefined || value === "") {
+          process.stderr.write(`--${name} needs a value\n`);
+          process.exit(1);
+        }
+        if (s.repeat) (flags[name] ??= []).push(value);
+        else flags[name] = value;
+      } else flags[name] = true;
+      continue;
+    }
+    positionals.push(a);
+  }
+  return { help: false, flags, positionals };
+}
+
+export function printHelp(usage, spec, notes = []) {
+  const lines = [`Usage: ${usage}`, ""];
+  const names = Object.keys(spec);
+  if (names.length) {
+    lines.push("Options:");
+    for (const n of names) lines.push(`  --${n}${spec[n].value ? " <value>" : ""}  ${spec[n].help}`);
+    lines.push("");
+  }
+  lines.push(...notes, "", "Exit codes: 0 ok · 1 the check failed or the arguments were wrong · 2 this machine is not connected to a tenant");
+  process.stdout.write(lines.join("\n") + "\n");
+}

package/skills/whats-happening/scripts/lib/credential.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// lib/credential.mjs — is this machine connected? The ONE place a skill script decides it, vendored
+// byte-identical into every skill's scripts/lib/ from skill-lib/credential.mjs at the package root
+// (`npm run skill-lib:sync`; a test fails on any drift). Skills install one directory at a time, so
+// each carries its own copy. This file is a library — run a sibling script with --help for usage.
+//
+// customer.json carries exactly one credential: a personal key (`key`), or the keyless login's
+// session (`auth`, the recommended rail). A script never reads either for its value: it spawns the
+// catalyst-skills CLI, which authenticates with whichever is present and refreshes a login's token
+// itself. A new credential kind lands here, once.
+
+/** The command that connects this machine, as every not-connected line names it. */
+export const CONNECT_COMMAND =
+  "npx @catalyst-cloud/catalyst-skills login (or, with a personal key: CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login)";
+
+/** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
+export function hasCredential(cfg) {
+  if (cfg === null || typeof cfg !== "object") return false;
+  const key = cfg["key"];
+  if (typeof key === "string" && key !== "") return true;
+  const login = cfg["auth"];
+  return (
+    login !== null &&
+    typeof login === "object" &&
+    login["kind"] === "oauth" &&
+    typeof login["refreshToken"] === "string" &&
+    login["refreshToken"] !== ""
+  );
+}

package/skills/whats-happening/scripts/snapshot.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+// snapshot.mjs — one call that answers "where are we?": the tenant contract (trimmed to what a
+// status reply needs), what is running, what is queued, what is waiting on a human, and whether the
+// local replica is fresh. Prints ONE JSON document on stdout and the source line on stderr.
+import { mustRun, parseFlags, parseJson, printHelp, runCli } from "./lib/cli.mjs";
+
+const SPEC = {
+  team: { value: true, help: "limit the queue and the board to this team key" },
+  board: { value: false, help: "also include open tickets grouped by stage, in the contract's slot order" },
+  limit: { value: true, help: "board: max tickets to read (default 200)" },
+  "full-contract": { value: false, help: "include the whole contract instead of the trimmed tenant block" },
+};
+
+const { help, flags } = parseFlags(process.argv.slice(2), SPEC);
+if (help) {
+  printHelp("node scripts/snapshot.mjs [--team K] [--board] [--limit N] [--full-contract] [--help]", SPEC, [
+    "Runs, in order: catalyst-skills contract, running, queue, ask list, replica status (and query issues with --board).",
+    "Output: one JSON document {takenAt, source, tenant, running, queue, waitingOnHuman, board?, errors?}.",
+    "A section the cloud refused is reported under errors and the rest still prints; exit 1 in that case.",
+    "Every tenant fact (stage names, thresholds, teams) comes from the contract in this output, never from prose.",
+  ]);
+  process.exit(0);
+}
+
+const errors = {};
+const section = (name, args) => {
+  const r = runCli(args);
+  if (r.code !== 0) {
+    errors[name] = (r.stderr || r.stdout || `exit ${r.code}`).trim().split("\n").at(-1);
+    return null;
+  }
+  return parseJson(r.stdout, name);
+};
+
+const contract = parseJson(mustRun(["contract", "--json"], { quiet: true }).stdout, "contract");
+// `replica status` exits 0 fresh, 1 stale, 3 absent — all three are verdicts with JSON on stdout,
+// not failures; only a non-JSON answer is an error.
+const replica = (() => {
+  const r = runCli(["replica", "status", "--json"]);
+  try {
+    return JSON.parse(r.stdout.trim());
+  } catch {
+    errors.replica = (r.stderr || r.stdout || `exit ${r.code}`).trim().split("\n").at(-1);
+    return { verdict: "unknown", cursor: null, heartbeatAgeMs: null };
+  }
+})();
+const running = section("running", ["running", "--json"]);
+const queue = section("queue", flags.team ? ["queue", "--team", flags.team, "--json"] : ["queue", "--json"]);
+const asks = section("waitingOnHuman", ["ask", "list", "--json"]);
+
+const out = {
+  takenAt: new Date().toISOString(),
+  source: {
+    reads: "api",
+    replica: replica.verdict,
+    replicaCursor: replica.cursor ?? null,
+    replicaHeartbeatAgeMs: replica.heartbeatAgeMs ?? null,
+  },
+  tenant: flags["full-contract"] ? contract : trimContract(contract, flags.team),
+  running,
+  queue,
+  waitingOnHuman: asks,
+};
+
+if (flags.board) {
+  const args = ["query", "issues", "--limit", String(flags.limit ?? 200), "--json"];
+  if (flags.team) args.push("--team", flags.team);
+  const r = runCli(args);
+  const sourceLine = (r.stderr.match(/^source: .*$/m) ?? [null])[0];
+  // A board read is a window (`--limit` stays the default), and a window the cloud cut short must
+  // say so rather than reading as the whole team.
+  const truncatedLine = (r.stderr.match(/^truncated at .*$/m) ?? [null])[0];
+  if (r.code !== 0) errors.board = (r.stderr || `exit ${r.code}`).trim().split("\n").at(-1);
+  else {
+    const rows = parseJson(r.stdout, "issues");
+    out.board = groupByStage(rows, contract, flags.team);
+    if (sourceLine) out.source.board = sourceLine.replace(/^source: /, "");
+    if (truncatedLine) out.source.boardTruncated = truncatedLine;
+  }
+}
+
+if (Object.keys(errors).length) out.errors = errors;
+process.stderr.write(`source: api for running/queue/asks; replica ${replica.verdict}${replica.cursor != null ? ` (cursor ${replica.cursor})` : ""}${out.source.board ? `; board from ${out.source.board}` : ""}\n`);
+process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+process.exit(Object.keys(errors).length ? 1 : 0);
+
+/** The contract facts a status reply needs, and nothing a reply should not paste. */
+function trimContract(doc, teamKey) {
+  const teams = (doc.teams ?? []).filter((t) => !teamKey || String(t.key ?? "").toUpperCase() === teamKey.toUpperCase());
+  return {
+    contractVersion: doc.contractVersion,
+    account: { slug: doc.account?.slug, name: doc.account?.name },
+    slots: doc.slots,
+    ladder: { phases: doc.ladder?.phases, intakeEnabled: doc.ladder?.intakeEnabled, keying: doc.ladder?.keying },
+    thresholds: doc.thresholds,
+    mergeDefaultPolicy: doc.merge?.defaultPolicy,
+    teams: teams.map((t) => ({
+      key: t.key,
+      name: t.name,
+      workflowMode: t.workflowMode,
+      readiness: t.readiness?.status,
+      stages: Object.fromEntries(
+        (doc.slots ?? Object.keys(t.stages ?? {}))
+          .filter((slot) => t.stages?.[slot])
+          .map((slot) => [slot, { name: t.stages[slot].name, type: t.stages[slot].type, stateStillExists: t.stages[slot].stateStillExists }]),
+      ),
+      labels: {
+        ask: (t.labels?.ask ?? []).map((l) => l.name),
+        hold: (t.labels?.hold ?? []).map((l) => l.name),
+        release: (t.labels?.release ?? []).map((l) => l.name),
+      },
+    })),
+  };
+}
+
+/** Open tickets by stage name, ordered by the contract's slot order for the ticket's team; unmapped
+ *  state names follow, alphabetically. Terminal-typed states are dropped so the board is work only. */
+function groupByStage(rows, doc, teamKey) {
+  const order = [];
+  const seen = new Set();
+  const terminal = new Set();
+  for (const t of doc.teams ?? []) {
+    if (teamKey && String(t.key ?? "").toUpperCase() !== teamKey.toUpperCase()) continue;
+    for (const slot of doc.slots ?? []) {
+      const s = t.stages?.[slot];
+      if (!s?.name) continue;
+      if (slot === "done" || slot === "canceled" || ["completed", "canceled", "cancelled"].includes(String(s.type ?? "").toLowerCase())) terminal.add(s.name);
+      else if (!seen.has(s.name)) {
+        seen.add(s.name);
+        order.push(s.name);
+      }
+    }
+  }
+  const byStage = {};
+  for (const r of rows) {
+    const state = String(r.state ?? "unknown");
+    if (terminal.has(state)) continue;
+    (byStage[state] ??= []).push({
+      identifier: r.identifier,
+      title: r.title,
+      priority: r.priority ?? null,
+      assignee: r.assignee_name ?? r.assignee ?? null,
+      updatedAt: r.updated_at ?? null,
+      projectId: r.project_id ?? null,
+    });
+  }
+  const extra = Object.keys(byStage).filter((s) => !seen.has(s)).sort();
+  return { stageOrder: [...order, ...extra], byStage, terminalStagesDropped: [...terminal] };
+}

package/vendor/README.md

@@ -0,0 +1,9 @@
+# Temporary paths runtime
+
+`paths/` contains the generated JavaScript and declarations from `@catalyst-cloud/paths`, catalyst-cloud commit `c391358d06720985126c15b7fa9d9d6ad1878211`, PR 6059. This avoids a separate implementation of the version 1 machine path contract while that package is private. Replace the imports with the published package when publication is approved.
+
+Run `CATALYST_PATHS_SOURCE=/path/to/catalyst-cloud node scripts/vendor-paths.mjs` to regenerate from that exact Git object. Add `--check` to compare a fresh compilation with the checked-in files. Without a source checkout, `npm run paths:check` validates each generated file against the recorded hashes. The generator uses this repository's locked TypeScript compiler.
+
+Replica selection is `--db` where accepted, `CATALYST_REPLICA_DB`, then the machine manifest's `replicaDb`. Before a machine manifest exists, the CLI retains its saved customer.json path or legacy default. A manifest without replicaDb leaves replication optional and unconfigured. A malformed or missing explicit manifest fails instead of selecting another database.
+
+The reader derives the lock from the selected database on each status check. No existing database is copied, moved, opened for writing, or reseeded by path resolution. Setup must import a discovered populated replica into the manifest before activating it. This PR does not install a manifest or start a writer.

package/vendor/paths/index.d.ts

@@ -0,0 +1,85 @@
+/** Pure POSIX path contract. No process globals or filesystem imports. */
+export declare const PATH_ROLES: {
+    readonly repoRoot: {
+        readonly variable: "CATALYST_REPO_ROOT";
+        readonly mode: "0755";
+    };
+    readonly worktrees: {
+        readonly variable: "CATALYST_WORKTREES_DIR";
+        readonly mode: "0755";
+    };
+    readonly logs: {
+        readonly variable: "CATALYST_LOGS_DIR";
+        readonly mode: "0755";
+    };
+    readonly events: {
+        readonly variable: "CATALYST_EVENTS_DIR";
+        readonly mode: "0755";
+    };
+    readonly config: {
+        readonly variable: "CATALYST_CONFIG_DIR";
+        readonly mode: "0700";
+    };
+    readonly cache: {
+        readonly variable: "CATALYST_CACHE_DIR";
+        readonly mode: "0755";
+    };
+    readonly state: {
+        readonly variable: "CATALYST_STATE_DIR";
+        readonly mode: "0755";
+    };
+    readonly skills: {
+        readonly variable: "CATALYST_SKILLS_DIR";
+        readonly mode: "0755";
+    };
+    readonly thoughtsRepo: {
+        readonly variable: "CATALYST_THOUGHTS_REPO";
+        readonly mode: "0755";
+    };
+    readonly replicaDb: {
+        readonly variable: "CATALYST_REPLICA_DB";
+        readonly mode: "0600";
+    };
+    readonly artifacts: {
+        readonly variable: "CATALYST_ARTIFACT_DIR";
+        readonly mode: "0700";
+    };
+};
+export type PathRole = keyof typeof PATH_ROLES;
+export type MachineRole = Exclude<PathRole, "artifacts">;
+export type Environment = Readonly<Record<string, string | undefined>>;
+export type PathOverrides = Readonly<Partial<Record<PathRole, string>>>;
+/** Mandatory v1 fields for setup/installer composers; optional roles have no setup default. */
+export declare const REQUIRED_MACHINE_PATH_ROLES: readonly ["repoRoot", "worktrees", "logs", "events", "config", "cache", "state", "skills"];
+export type MachinePathValues = Record<(typeof REQUIRED_MACHINE_PATH_ROLES)[number], string> & {
+    replicaDb?: string;
+    thoughtsRepo?: string;
+};
+export type PathProvenance = "explicit" | "environment" | "imported" | "default";
+export interface MachinePaths {
+    readonly version: 1;
+    readonly paths: MachinePathValues;
+    readonly provenance: Partial<Record<MachineRole, PathProvenance>>;
+}
+export type Profile = "workstation" | "container";
+export interface ResolveOptions {
+    readonly profile?: Profile;
+    readonly overrides?: PathOverrides;
+    readonly env?: Environment;
+    /** Explicitly selected record; the Node adapter owns implicit discovery. */
+    readonly machine?: MachinePaths;
+}
+export declare function absolutePath(value: unknown, name: string): string;
+/** Reject extra fields, including credentials and per-run artifacts. */
+export declare function parseMachinePaths(value: unknown): MachinePaths;
+export declare function resolveCatalystPath(role: string, options?: ResolveOptions): string;
+export interface ProposalOptions {
+    readonly env: Environment;
+    readonly overrides?: PathOverrides;
+    readonly existing?: MachinePaths;
+    /** Existing locations, never relocated contents. */
+    readonly discovered?: Partial<Record<MachineRole, string>>;
+}
+/** Setup only. Runtime never calls this and this function never writes. */
+export declare function proposeMachinePaths(options: ProposalOptions): MachinePaths;
+export { CATALYST_DIRECTORY_ROLES as LEGACY_DIRECTORY_ROLES, CREATABLE_DIRECTORY_ROLES as LEGACY_CREATABLE_DIRECTORY_ROLES, LEGACY_BASE_SHELL, resolveWorkstationDir, type CatalystDirectoryRole, type DirectoryBase, } from "./legacy-installer.js";

package/vendor/paths/index.js

@@ -0,0 +1,148 @@
+/** Pure POSIX path contract. No process globals or filesystem imports. */
+export const PATH_ROLES = {
+    repoRoot: { variable: "CATALYST_REPO_ROOT", mode: "0755" },
+    worktrees: { variable: "CATALYST_WORKTREES_DIR", mode: "0755" },
+    logs: { variable: "CATALYST_LOGS_DIR", mode: "0755" },
+    events: { variable: "CATALYST_EVENTS_DIR", mode: "0755" },
+    config: { variable: "CATALYST_CONFIG_DIR", mode: "0700" },
+    cache: { variable: "CATALYST_CACHE_DIR", mode: "0755" },
+    state: { variable: "CATALYST_STATE_DIR", mode: "0755" },
+    skills: { variable: "CATALYST_SKILLS_DIR", mode: "0755" },
+    thoughtsRepo: { variable: "CATALYST_THOUGHTS_REPO", mode: "0755" },
+    replicaDb: { variable: "CATALYST_REPLICA_DB", mode: "0600" },
+    artifacts: { variable: "CATALYST_ARTIFACT_DIR", mode: "0700" },
+};
+/** Mandatory v1 fields for setup/installer composers; optional roles have no setup default. */
+export const REQUIRED_MACHINE_PATH_ROLES = [
+    "repoRoot",
+    "worktrees",
+    "logs",
+    "events",
+    "config",
+    "cache",
+    "state",
+    "skills",
+];
+export function absolutePath(value, name) {
+    if (typeof value !== "string" || !value.startsWith("/") || value.includes("\0")) {
+        throw new Error(`paths: ${name} must be an absolute POSIX path`);
+    }
+    return value;
+}
+function isRole(role) {
+    return Object.hasOwn(PATH_ROLES, role);
+}
+function object(value, name) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error(`paths: ${name} must be an object`);
+    return Object.fromEntries(Object.entries(value));
+}
+function keys(value, allowed, name) {
+    for (const key of Object.keys(value))
+        if (!allowed.includes(key))
+            throw new Error(`paths: unknown ${name} field ${key}`);
+}
+/** Reject extra fields, including credentials and per-run artifacts. */
+export function parseMachinePaths(value) {
+    const record = object(value, "machine record");
+    keys(record, ["version", "paths", "provenance"], "machine record");
+    if (record.version !== 1)
+        throw new Error(`paths: unsupported machine record version ${String(record.version)}`);
+    const paths = object(record.paths, "paths");
+    const provenance = object(record.provenance, "provenance");
+    const roles = Object.keys(PATH_ROLES).filter((role) => role !== "artifacts");
+    keys(paths, roles, "paths");
+    keys(provenance, roles, "provenance");
+    const validated = {
+        repoRoot: absolutePath(paths.repoRoot, "repoRoot"),
+        worktrees: absolutePath(paths.worktrees, "worktrees"),
+        logs: absolutePath(paths.logs, "logs"),
+        events: absolutePath(paths.events, "events"),
+        config: absolutePath(paths.config, "config"),
+        cache: absolutePath(paths.cache, "cache"),
+        state: absolutePath(paths.state, "state"),
+        skills: absolutePath(paths.skills, "skills"),
+    };
+    if (Object.hasOwn(paths, "replicaDb"))
+        validated.replicaDb = absolutePath(paths.replicaDb, "replicaDb");
+    if (Object.hasOwn(paths, "thoughtsRepo"))
+        validated.thoughtsRepo = absolutePath(paths.thoughtsRepo, "thoughtsRepo");
+    const sources = {};
+    for (const [role, source] of Object.entries(provenance)) {
+        if (!isRole(role) || role === "artifacts" || !Object.hasOwn(validated, role))
+            throw new Error(`paths: provenance has no path for ${role}`);
+        if (source !== "explicit" &&
+            source !== "environment" &&
+            source !== "imported" &&
+            source !== "default")
+            throw new Error(`paths: invalid provenance for ${role}`);
+        sources[role] = source;
+    }
+    return { version: 1, paths: validated, provenance: sources };
+}
+export function resolveCatalystPath(role, options = {}) {
+    if (!isRole(role))
+        throw new Error(`paths: unknown role ${role}`);
+    const variable = PATH_ROLES[role].variable;
+    const explicit = options.overrides?.[role];
+    if (explicit !== undefined)
+        return absolutePath(explicit, role);
+    const environment = options.env?.[variable];
+    if (environment !== undefined)
+        return absolutePath(environment, variable);
+    if (options.machine && role !== "artifacts") {
+        const path = parseMachinePaths(options.machine).paths[role];
+        if (path !== undefined)
+            return path;
+    }
+    throw new Error(`paths: ${variable} is not set; declare ${role} explicitly or run paths configure`);
+}
+/** Setup only. Runtime never calls this and this function never writes. */
+export function proposeMachinePaths(options) {
+    const existing = options.existing && parseMachinePaths(options.existing);
+    const paths = {};
+    const provenance = {};
+    const env = options.env;
+    const home = () => absolutePath(env.HOME, "HOME");
+    const base = (variable, fallback) => absolutePath(env[variable] ?? fallback(), variable);
+    const defaults = {
+        repoRoot: () => `${base("CATALYST_HOME", () => `${home()}/catalyst`)}/repos`,
+        worktrees: () => `${base("CATALYST_HOME", () => `${home()}/catalyst`)}/wt`,
+        logs: () => `${base("XDG_STATE_HOME", () => `${home()}/.local/state`)}/catalyst/logs`,
+        events: () => `${base("XDG_STATE_HOME", () => `${home()}/.local/state`)}/catalyst/events`,
+        config: () => `${base("XDG_CONFIG_HOME", () => `${home()}/.config`)}/catalyst`,
+        cache: () => `${base("XDG_CACHE_HOME", () => `${home()}/.cache`)}/catalyst`,
+        state: () => `${base("XDG_STATE_HOME", () => `${home()}/.local/state`)}/catalyst`,
+        skills: () => `${home()}/.agents/skills`,
+    };
+    for (const role of Object.keys(PATH_ROLES)) {
+        if (!isRole(role) || role === "artifacts")
+            continue;
+        const explicit = options.overrides?.[role];
+        const environment = env[PATH_ROLES[role].variable];
+        const accepted = existing?.paths[role];
+        const imported = options.discovered?.[role];
+        const value = explicit ??
+            environment ??
+            accepted ??
+            imported ??
+            (role === "replicaDb" || role === "thoughtsRepo" ? undefined : defaults[role]());
+        if (value === undefined)
+            continue;
+        paths[role] = absolutePath(value, role);
+        const source = explicit !== undefined
+            ? "explicit"
+            : environment !== undefined
+                ? "environment"
+                : accepted !== undefined
+                    ? existing?.provenance[role]
+                    : imported !== undefined
+                        ? "imported"
+                        : "default";
+        if (source !== undefined)
+            provenance[role] = source;
+    }
+    return parseMachinePaths({ version: 1, paths, provenance });
+}
+// Transitional installer adapter only. Runtime callers must use resolveCatalystPath.
+export { CATALYST_DIRECTORY_ROLES as LEGACY_DIRECTORY_ROLES, CREATABLE_DIRECTORY_ROLES as LEGACY_CREATABLE_DIRECTORY_ROLES, LEGACY_BASE_SHELL, resolveWorkstationDir, } from "./legacy-installer.js";

package/vendor/paths/legacy-installer.d.ts

@@ -0,0 +1,36 @@
+/** Where a role's directory lives when no explicit environment variable overrides it. */
+export type DirectoryBase = "catalyst-home" | "xdg-state" | "xdg-config" | "xdg-cache" | "xdg-data" | "none";
+export interface CatalystDirectoryRole {
+    /** CTC-2548's role id, verbatim. */
+    readonly role: string;
+    /** CTC-2548's canonical environment variable for this role, verbatim. */
+    readonly variable: string;
+    /** "none" ⇒ this role has no default and always refuses without the explicit variable. */
+    readonly base: DirectoryBase;
+    /** Path segments appended to the resolved base, in order. */
+    readonly segments: readonly string[];
+    /** false ⇒ setup never creates this directory (artifacts is minted per run, not provisioned). */
+    readonly creatable: boolean;
+    /** 0700 for anything holding a credential or machine state; 0755 otherwise. */
+    readonly mode: "0700" | "0755";
+}
+/**
+ * The ten roles, in CTC-2548's own order. `artifacts` is last-but-one and is the one role with
+ * `base: "none"` — it is minted per run by the caller (`CATALYST_ARTIFACT_DIR`) and this script
+ * must never invent a default for it.
+ */
+export declare const CATALYST_DIRECTORY_ROLES: readonly CatalystDirectoryRole[];
+/** The roles setup actually creates, in table order. Never hand-counted (CTC-2552 was exactly that bug). */
+export declare const CREATABLE_DIRECTORY_ROLES: readonly CatalystDirectoryRole[];
+type Env = Record<string, string | undefined>;
+/** The shell expression for a base's default (mirrors {@link baseDefault}, rendered instead of resolved). */
+export declare const LEGACY_BASE_SHELL: Record<DirectoryBase, string | null>;
+/**
+ * Resolve one role's directory from `env`, the same precedence a shell caller gets from the
+ * rendered block: explicit variable → base default → a NAMED refusal, never a relative guess
+ * (the house shape: apps/host-sync/src/cli.ts:801-812).
+ */
+export declare function resolveWorkstationDir(role: string, env: Env): string | {
+    readonly refused: string;
+};
+export {};