@catalyst-cloud/cli 0.13.0 → 0.14.0

package/dist/project.js

@@ -0,0 +1,191 @@
+// project.ts — `catalyst project wip-limit get|set`: a project's new-start WIP limit, on the
+// person's own login. Any active member reads it; a workspace owner or admin sets it. The limit is
+// per Catalyst project (one Linear team across all its repositories): the project's stored value,
+// else the workspace value, else the default the cloud reports. It holds only NEW starts, so the
+// reply carries the work in progress beside the limit: that count, not a runner count, is what a
+// person compares. The route is the cloud's own member route; the reply shape is the cloud's, so a
+// field this CLI does not know is passed through under --json untouched.
+import { flagString, positionals } from "./args.js";
+import { requireConfig } from "./config.js";
+import { loadContract } from "./contract.js";
+import { UsageError } from "./errors.js";
+import { apiClient } from "./transport.js";
+/** The limit's bounds, as the cloud clamps them. A value outside is refused here, before any request. */
+export const WIP_LIMIT_MIN = 0;
+export const WIP_LIMIT_MAX = 9999;
+/** The agent twin of the member route: a bearer reads it with `?team=<key or id>` and writes it with a
+ *  body naming the team, the way the team-workflow verbs do. The contract's route table lists these
+ *  two strings, so `capabilities` can judge them. */
+export const WIP_LIMIT_ROUTE = "/api/v1/agent/team-wip-limit";
+export const wipLimitPath = (team) => `${WIP_LIMIT_ROUTE}?team=${encodeURIComponent(team)}`;
+/** Admin-readable inventory of every Catalyst project, including projects with no saved stages. */
+export const PROJECT_LIST_ROUTE_SUFFIX = "/tenant/repositories";
+const SOURCE_TEXT = {
+    project: "set for this project",
+    flag: "workspace value",
+    default: "default",
+};
+const sourceText = (source) => SOURCE_TEXT[String(source)] ?? String(source ?? "unknown");
+/** The project `--team` names, or the only mapped project when the flag is absent. Never a guess between two. */
+export function resolveTeam(doc, wanted) {
+    const teams = Array.isArray(doc.teams) ? doc.teams : [];
+    if (wanted !== undefined) {
+        const lower = wanted.toLocaleLowerCase();
+        const found = teams.find((t) => (t.key ?? "").toLocaleLowerCase() === lower || t.id === wanted);
+        if (!found)
+            throw new UsageError(`no mapped project has the team key ${wanted}${teams.length ? ` (mapped: ${teams.map((t) => t.key ?? t.id).join(", ")})` : " (no project is mapped yet)"}`);
+        return found;
+    }
+    if (teams.length === 1)
+        return teams[0];
+    if (teams.length === 0)
+        throw new UsageError("no project is mapped yet; map one first (catalyst team map <KEY>)");
+    throw new UsageError(`--team is needed: ${teams.length} projects are mapped (${teams.map((t) => t.key ?? t.id).join(", ")})`);
+}
+/** `set`'s value: an integer inside the cloud's bounds, or the word default. Parsed before any request. */
+export function parseLimit(raw) {
+    if (raw === undefined)
+        throw new UsageError("project wip-limit set needs a value: an integer, or default");
+    if (raw === "default")
+        return null;
+    if (!/^-?\d+$/.test(raw))
+        throw new UsageError(`the limit must be an integer from ${WIP_LIMIT_MIN} to ${WIP_LIMIT_MAX}, or default (got ${raw})`);
+    const n = Number(raw);
+    if (n < WIP_LIMIT_MIN || n > WIP_LIMIT_MAX)
+        throw new UsageError(`the limit must be from ${WIP_LIMIT_MIN} to ${WIP_LIMIT_MAX} (got ${raw}); 0 holds every new start`);
+    return n;
+}
+/** The in-progress tickets as identifiers, tolerant of the cloud sending strings or objects; [] when absent. */
+export function ticketIds(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((t) => typeof t === "string"
+        ? t
+        : t && typeof t === "object"
+            ? String(t.identifier ??
+                t.id ??
+                "")
+            : "")
+        .filter((t) => t !== "");
+}
+/** One line naming what holds the WIP, capped so a big team does not scroll; null when the cloud sent none. */
+function inProgressLine(view) {
+    const ids = ticketIds(view.inProgressTickets);
+    if (ids.length === 0)
+        return null;
+    const shown = ids.slice(0, 12);
+    return `in progress: ${shown.join(", ")}${ids.length > shown.length ? ` and ${ids.length - shown.length} more` : ""} — these are what a new ticket waits on; unstick them, not the queue`;
+}
+function line(key, view) {
+    const limit = view.limit;
+    const inProgress = view.inProgress;
+    const at = typeof limit === "number" &&
+        typeof inProgress === "number" &&
+        inProgress >= limit
+        ? " — at the limit: a new ticket waits until one in progress finishes"
+        : "";
+    return `${key}: ${typeof inProgress === "number" ? inProgress : "?"} in progress, limit ${typeof limit === "number" ? limit : "?"} (${sourceText(view.source)})${at}`;
+}
+export async function cmdProject(args, ctx) {
+    const [sub, action, value, ...extra] = positionals(args);
+    if (sub === "list") {
+        if (action !== undefined || value !== undefined || extra.length > 0)
+            throw new UsageError("project list takes no arguments");
+        const cfg = requireConfig(ctx);
+        const { doc } = await loadContract(ctx, cfg);
+        const route = doc.routes.find((r) => r.method === "GET" && r.path.endsWith(PROJECT_LIST_ROUTE_SUFFIX));
+        if (!route)
+            throw new UsageError("this cloud does not publish the tenant project list route yet (needs a newer cloud)");
+        const response = await apiClient(cfg, ctx).getJson(route.path, { accept: [403, 404] });
+        if (response.status === 403) {
+            const message = response.body
+                ?.message;
+            throw new UsageError(`listing tenant projects needs a workspace owner or admin${message ? ` (${message})` : ""}`);
+        }
+        if (response.status === 404)
+            throw new UsageError("this cloud does not serve tenant project listing yet (needs a newer cloud)");
+        const projects = Array.isArray(response.body?.repositories)
+            ? response.body.repositories
+            : [];
+        if (projects.length === 0 && !Array.isArray(response.body?.repositories)) {
+            throw new UsageError("the tenant project list response did not contain repositories");
+        }
+        if (args.json)
+            ctx.stdout(JSON.stringify(projects));
+        else {
+            for (const project of projects) {
+                ctx.stdout(`${project.name} | ${project.linearTeamKey ?? project.linearTeamId} | ${project.githubRepoOwner}/${project.githubRepoName} | ${project.status} | ${project.id}`);
+            }
+        }
+        return 0;
+    }
+    if (sub !== "wip-limit")
+        throw new UsageError("project needs wip-limit <get|set <n>|default>");
+    if (action !== "get" && action !== "set")
+        throw new UsageError("project wip-limit needs get, or set <n>|default");
+    if (action === "get" && value !== undefined)
+        throw new UsageError("project wip-limit get takes no value; set does");
+    if (extra.length > 0)
+        throw new UsageError("project wip-limit takes one value at most");
+    const limit = action === "set" ? parseLimit(value) : null;
+    const cfg = requireConfig(ctx);
+    const { doc } = await loadContract(ctx, cfg);
+    const team = resolveTeam(doc, flagString(args, "team"));
+    const key = team.key ?? team.id;
+    const client = apiClient(cfg, ctx);
+    const accept = [400, 403, 404];
+    const emit = (body, lines) => {
+        if (args.json)
+            ctx.stdout(JSON.stringify(body));
+        else
+            for (const l of lines)
+                ctx.stdout(l);
+    };
+    const refuse = (status, reply) => {
+        // The cloud's error bodies carry `error` (the code to match on) and a human `message`.
+        const body = reply ?? {};
+        const detail = body.message || body.reason
+            ? ` (${String(body.message ?? body.reason)})`
+            : "";
+        const why = status === 403
+            ? `setting the limit needs a workspace owner or admin; any member can read it with catalyst project wip-limit get${detail}`
+            : status === 404 && body.error === "team-unknown"
+                ? `this cloud does not know a team ${key}; check the key with catalyst team list${detail}`
+                : status === 404
+                    ? "this Catalyst Cloud does not serve the wip-limit route yet (needs a newer cloud)"
+                    : `${String(body.error ?? body.code ?? "bad request")}${detail}`;
+        emit({ status, team: { id: team.id, key }, ...body }, [
+            `refused (${status}): ${why}`,
+        ]);
+        return 1;
+    };
+    const before = await client.getJson(wipLimitPath(team.id), {
+        accept,
+        parseAccepted: true,
+    });
+    if (before.status !== 200)
+        return refuse(before.status, before.body);
+    if (action === "get") {
+        emit({ team: { id: team.id, key }, ...before.body }, [
+            line(key, before.body),
+            ...(inProgressLine(before.body) === null
+                ? []
+                : [inProgressLine(before.body)]),
+            `change it: catalyst project wip-limit set <n> --team ${key} (owner or admin; set default returns to the workspace value)`,
+        ]);
+        return 0;
+    }
+    const after = await client.postJson(WIP_LIMIT_ROUTE, { team: team.id, limit }, { accept });
+    if (after.status !== 200)
+        return refuse(after.status, after.body);
+    emit({
+        team: { id: team.id, key },
+        ...after.body,
+        previous: { limit: before.body.limit, source: before.body.source },
+    }, [
+        `${key}: limit ${String(before.body.limit)} (${sourceText(before.body.source)}) → ${String(after.body.limit)} (${sourceText(after.body.source)})${after.body.limit === 0 ? "; 0 holds every new start" : ""}`,
+        line(key, after.body),
+    ]);
+    return 0;
+}

package/dist/ready.js

@@ -131,12 +131,22 @@ function unresolvedLine(u) {
  *  identifier or a repository name, never a value, and nothing here reads a value. Any other check
  *  keeps the generic line. */
 function teamCheckFix(label, c) {
+    const automationRules = {
+        linear_automation_pr_open: "On PR open",
+        linear_automation_pr_review: "On PR review request or activity",
+        linear_automation_pr_ready: "On PR ready for merge",
+        linear_automation_pr_merge: "On PR merge",
+    };
+    const rule = automationRules[c.id];
+    if (rule) {
+        return `in Linear, open Settings → Teams → ${label} → Workflow → Workflows & automations → Pull request and commit automations and set ${rule} to No action, including branch-specific overrides; then run catalyst team check ${label}`;
+    }
     const unresolved = unresolvedList(c.unresolved);
     const unresolvedNames = new Set(unresolved.map((u) => u.name));
     const names = nameList(c.names).filter((n) => !unresolvedNames.has(n));
     const parts = [];
     if (names.length > 0) {
-        parts.push(`set ${names.join(", ")} on the repository's Environment page under Settings → Repositories ` +
+        parts.push(`set ${names.join(", ")} on the repository's Environment page under Settings → Your projects → the project → Repositories → the repository ` +
             `(team ${label}; ${names.length === 1 ? "it has" : "they have"} no value at repository or account scope)`);
     }
     for (const u of unresolved)

package/dist/release.js

@@ -1,4 +1,4 @@
-// release.ts — `catalyst-skills release`: a person's release of a parked or held ticket, or of every
+// release.ts — `catalyst release`: a person's release of a parked or held ticket, or of every
 // ticket on one team parked under one failure class, through the contract's `ticket-release` and
 // `ticket-release-class` routes. The cloud reads every governor holding the ticket and either releases
 // all of them or releases nothing and names, per governor, the human action that does fix it; this verb

package/dist/repo.js

@@ -0,0 +1,297 @@
+// repo.ts — `catalyst repo agents-block` and `catalyst repo agent-setup`: a repository's agent setup,
+// read and changed in a checkout the person names, never through git and never through the cloud.
+//
+//   repo agents-block <path> [--write]        the one Catalyst block in AGENTS.md, marker-delimited,
+//                                             replaced in place on a rerun (never duplicated)
+//   repo agent-setup <path> [--apply] [--with-check]
+//                                             what the repository holds for agents, whether it is
+//                                             portable, the plan that would make it so, and --apply
+//
+// Portable means: AGENTS.md is canonical; CLAUDE.md is a thin file that imports it with a line that
+// is exactly `@AGENTS.md` plus Claude-only notes; `.agents/skills` and `.agents/rules` are canonical
+// and `.claude/skills` and `.claude/rules` are relative symlinks to them. Every write lands in the
+// working tree only: committing, branching and the pull request are the person's, in the open.
+import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, renameSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { flagBool, positionals } from "./args.js";
+import { UsageError } from "./errors.js";
+export const BLOCK_START = "<!-- catalyst:start -->";
+export const BLOCK_END = "<!-- catalyst:end -->";
+/** The two skills the block names. ONE place each: the packs are being consolidated, and a rename
+ *  lands here, then `repo agents-block --write` brings every repository's block up to date. */
+export const BLOCK_PROCESS_SKILL = "whats-happening";
+export const BLOCK_DECISION_SKILL = "catalyst-sop";
+/** ⭐ THE block, word for word. Harness-agnostic; names the skills, never the process. */
+export const CATALYST_AGENTS_BLOCK = [
+    BLOCK_START,
+    "## Catalyst",
+    "",
+    `This repository is worked through Catalyst: tickets move through a pipeline of agent-run phases, and pull requests merge through its queue. Before you plan, branch, review or merge here, load the skill that explains the process instead of inferring it from this file: \`${BLOCK_PROCESS_SKILL}\` (how a ticket runs, what each phase produces, why work waits), and \`${BLOCK_DECISION_SKILL}\` when it is installed (what to do when work stalls on a decision). Keep this block as it is; onboarding maintains it.`,
+    BLOCK_END,
+].join("\n");
+/** Where the block sits in `text`, or null. Only the FIRST start marker and the first end after it count. */
+function locateBlock(text) {
+    const start = text.indexOf(BLOCK_START);
+    if (start === -1)
+        return null;
+    const endAt = text.indexOf(BLOCK_END, start);
+    if (endAt === -1)
+        return null;
+    return { start, end: endAt + BLOCK_END.length };
+}
+/** The block's state in an AGENTS.md text (`null` text = no file). */
+export function blockState(text) {
+    if (text === null)
+        return "absent";
+    const at = locateBlock(text);
+    if (at === null)
+        return "missing";
+    return text.slice(at.start, at.end) === CATALYST_AGENTS_BLOCK ? "current" : "stale";
+}
+/** The text with the block current: replaced in place, appended after one blank line, or the whole
+ *  file. Pure and idempotent: applying it to its own output changes nothing. */
+export function withBlock(text) {
+    if (text === null || text.trim() === "")
+        return `${CATALYST_AGENTS_BLOCK}\n`;
+    const at = locateBlock(text);
+    if (at !== null)
+        return `${text.slice(0, at.start)}${CATALYST_AGENTS_BLOCK}${text.slice(at.end)}`;
+    const body = text.replace(/\s+$/, "");
+    return `${body}\n\n${CATALYST_AGENTS_BLOCK}\n`;
+}
+function linkState(root, rel, canonicalRel) {
+    const p = join(root, rel);
+    let st;
+    try {
+        st = lstatSync(p);
+    }
+    catch {
+        return { kind: "absent" };
+    }
+    if (st.isSymbolicLink()) {
+        const target = readlinkSync(p);
+        const resolved = resolve(dirname(p), target);
+        return { kind: "symlink", target, resolvesToCanonical: resolved === resolve(root, canonicalRel) && existsSync(resolved) };
+    }
+    return st.isDirectory() ? { kind: "dir" } : { kind: "file" };
+}
+const OTHER_MARKERS = [".codex", ".cursor", ".cursorrules", ".windsurfrules", "GEMINI.md", ".github/copilot-instructions.md"];
+/** Read a checkout's agent setup. Never writes. */
+export function inspectRepo(root) {
+    const agentsPath = join(root, "AGENTS.md");
+    const claudePath = join(root, "CLAUDE.md");
+    const agentsText = existsSync(agentsPath) ? readFileSync(agentsPath, "utf8") : null;
+    const claudeText = existsSync(claudePath) ? readFileSync(claudePath, "utf8") : null;
+    const claudeLines = claudeText === null ? [] : claudeText.split("\n");
+    const importsAgentsMd = claudeLines.some((l) => l.trim() === "@AGENTS.md");
+    const otherLines = claudeLines.filter((l) => l.trim() !== "" && l.trim() !== "@AGENTS.md").length;
+    const report = {
+        path: root,
+        agentsMd: { present: agentsText !== null, lines: agentsText === null ? 0 : agentsText.replace(/\n$/, "").split("\n").length, bytes: agentsText === null ? 0 : Buffer.byteLength(agentsText), block: blockState(agentsText) },
+        claudeMd: { present: claudeText !== null, importsAgentsMd, otherLines },
+        agentsDir: { skills: isDir(join(root, ".agents", "skills")), rules: isDir(join(root, ".agents", "rules")) },
+        claudeDir: { skills: linkState(root, ".claude/skills", ".agents/skills"), rules: linkState(root, ".claude/rules", ".agents/rules") },
+        others: OTHER_MARKERS.filter((m) => existsSync(join(root, m))),
+        verdict: "portable",
+        plan: [],
+        blockers: [],
+    };
+    // CLAUDE.md with guidance of its own and no import: its content belongs in AGENTS.md.
+    if (report.claudeMd.present && !importsAgentsMd) {
+        report.plan.push(report.agentsMd.present
+            ? "append CLAUDE.md's content to AGENTS.md and leave CLAUDE.md as the thin importer (`@AGENTS.md` plus Claude-only notes)"
+            : "create AGENTS.md from CLAUDE.md's content and leave CLAUDE.md as the thin importer (`@AGENTS.md`)");
+    }
+    else if (!report.agentsMd.present && !report.claudeMd.present) {
+        report.plan.push("create AGENTS.md (the Catalyst block starts it; add the repository's own guidance there)");
+    }
+    for (const name of ["skills", "rules"]) {
+        const c = report.claudeDir[name];
+        const canonical = report.agentsDir[name];
+        if (c.kind === "dir" && !canonical)
+            report.plan.push(`move .claude/${name} to .agents/${name} and leave .claude/${name} as a relative symlink to it`);
+        else if (c.kind === "dir" && canonical)
+            report.blockers.push(`.claude/${name} and .agents/${name} are both real directories: merge them by hand, then leave .claude/${name} as a relative symlink`);
+        else if (c.kind === "symlink" && !c.resolvesToCanonical)
+            report.blockers.push(`.claude/${name} is a symlink to ${c.target}, not to .agents/${name}: point it there by hand`);
+        else if (c.kind === "absent" && canonical)
+            report.plan.push(`add .claude/${name} as a relative symlink to .agents/${name}`);
+        else if (c.kind === "file")
+            report.blockers.push(`.claude/${name} is a file, not a directory: look at it by hand`);
+    }
+    if (report.blockers.length > 0)
+        report.verdict = "needs_hand_merge";
+    else if (report.plan.length > 0)
+        report.verdict = "convertible";
+    return report;
+}
+function isDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+const THIN_CLAUDE_MD = "# CLAUDE.md\n\nAll project context for any coding agent is in AGENTS.md, imported below. Only Claude-specific notes belong in this file.\n\n@AGENTS.md\n";
+/** Perform a convertible plan in the working tree. Refuses when anything needs a hand merge. */
+export function applyPlan(root, before) {
+    if (before.verdict === "needs_hand_merge")
+        throw new UsageError(`nothing applied: ${before.blockers.join("; ")}`);
+    const done = [];
+    const agentsPath = join(root, "AGENTS.md");
+    const claudePath = join(root, "CLAUDE.md");
+    if (before.claudeMd.present && !before.claudeMd.importsAgentsMd) {
+        const claudeText = readFileSync(claudePath, "utf8");
+        const existing = existsSync(agentsPath) ? readFileSync(agentsPath, "utf8").replace(/\s+$/, "") : "";
+        const merged = existing === "" ? claudeText.replace(/\s+$/, "") + "\n" : `${existing}\n\n${claudeText.replace(/\s+$/, "")}\n`;
+        writeFileSync(agentsPath, merged);
+        writeFileSync(claudePath, THIN_CLAUDE_MD);
+        done.push(before.agentsMd.present ? "appended CLAUDE.md's content to AGENTS.md; CLAUDE.md now imports it" : "created AGENTS.md from CLAUDE.md; CLAUDE.md now imports it");
+    }
+    else if (!before.agentsMd.present && !before.claudeMd.present) {
+        writeFileSync(agentsPath, withBlock(null));
+        done.push("created AGENTS.md holding the Catalyst block");
+    }
+    for (const name of ["skills", "rules"]) {
+        const c = before.claudeDir[name];
+        const canonicalPath = join(root, ".agents", name);
+        const claudeLink = join(root, ".claude", name);
+        if (c.kind === "dir" && !before.agentsDir[name]) {
+            mkdirSync(join(root, ".agents"), { recursive: true });
+            renameSync(claudeLink, canonicalPath);
+            symlinkSync(relative(dirname(claudeLink), canonicalPath), claudeLink, "dir");
+            done.push(`moved .claude/${name} to .agents/${name} and left a relative symlink`);
+        }
+        else if (c.kind === "absent" && before.agentsDir[name]) {
+            mkdirSync(join(root, ".claude"), { recursive: true });
+            symlinkSync(relative(dirname(claudeLink), canonicalPath), claudeLink, "dir");
+            done.push(`added .claude/${name} as a relative symlink to .agents/${name}`);
+        }
+    }
+    return done;
+}
+/** The lightweight check a customer can run in CI: node only, no dependencies, exit 1 on a finding. */
+export const AGENTS_MD_CHECK_SCRIPT = `#!/usr/bin/env node
+// agents-md-check.mjs — keeps this repository's agent setup portable. Run it in CI:
+//   node scripts/agents-md-check.mjs
+// It fails when CLAUDE.md stops importing AGENTS.md, when .claude/skills or .claude/rules stops being
+// a relative symlink into .agents/, when AGENTS.md outgrows its budget, or when a repository path
+// AGENTS.md cites no longer exists. Budgets: AGENTS_MD_MAX_LINES and AGENTS_MD_MAX_BYTES (env).
+import { existsSync, lstatSync, readFileSync, readlinkSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+const root = process.cwd();
+const maxLines = Number(process.env.AGENTS_MD_MAX_LINES ?? 120);
+const maxBytes = Number(process.env.AGENTS_MD_MAX_BYTES ?? 16 * 1024);
+const findings = [];
+const agents = existsSync("AGENTS.md") ? readFileSync("AGENTS.md", "utf8") : null;
+if (agents === null) findings.push("AGENTS.md is missing");
+else {
+  const lines = agents.replace(/\\n$/, "").split("\\n");
+  if (lines.length > maxLines) findings.push(\`AGENTS.md is \${lines.length} lines (budget \${maxLines})\`);
+  if (Buffer.byteLength(agents) > maxBytes) findings.push(\`AGENTS.md is \${Buffer.byteLength(agents)} bytes (budget \${maxBytes})\`);
+  for (const m of agents.matchAll(/\`([\\w.-]+(?:\\/[\\w.-]+)+)\`/g)) {
+    const p = m[1];
+    if (!existsSync(resolve(root, p))) findings.push(\`AGENTS.md cites \${p}, which does not exist\`);
+  }
+}
+if (existsSync("CLAUDE.md")) {
+  const n = readFileSync("CLAUDE.md", "utf8").split("\\n").filter((l) => l.trim() === "@AGENTS.md").length;
+  if (n !== 1) findings.push(\`CLAUDE.md must import AGENTS.md on exactly one line reading @AGENTS.md (found \${n})\`);
+}
+for (const name of ["skills", "rules"]) {
+  const link = \`.claude/\${name}\`;
+  const canonical = \`.agents/\${name}\`;
+  if (!existsSync(canonical) && !existsSync(link)) continue;
+  let st;
+  try { st = lstatSync(link); } catch { findings.push(\`\${link} is missing; make it a relative symlink to \${canonical}\`); continue; }
+  if (!st.isSymbolicLink()) { findings.push(\`\${link} is a real \${st.isDirectory() ? "directory" : "file"}; make \${canonical} canonical and \${link} a relative symlink\`); continue; }
+  const target = readlinkSync(link);
+  if (target.startsWith("/")) findings.push(\`\${link} is an absolute symlink (\${target}); make it relative\`);
+  if (resolve(dirname(link), target) !== resolve(root, canonical)) findings.push(\`\${link} points at \${target}, not \${canonical}\`);
+}
+for (const f of findings) console.error(\`agents-md-check: \${f}\`);
+if (findings.length > 0) process.exit(1);
+console.log("agents-md-check: portable");
+`;
+const describeLink = (s) => (s.kind === "symlink" ? `symlink → ${s.target}${s.resolvesToCanonical ? "" : " (not the canonical directory)"}` : s.kind === "dir" ? "real directory" : s.kind === "file" ? "a file" : "absent");
+export function reportLines(r) {
+    const lines = [
+        `repository: ${r.path}`,
+        `AGENTS.md: ${r.agentsMd.present ? `${r.agentsMd.lines} lines, ${r.agentsMd.bytes} bytes; Catalyst block ${r.agentsMd.block}` : "absent"}`,
+        `CLAUDE.md: ${r.claudeMd.present ? (r.claudeMd.importsAgentsMd ? `imports AGENTS.md${r.claudeMd.otherLines ? ` plus ${r.claudeMd.otherLines} lines of Claude-only notes` : ""}` : `${r.claudeMd.otherLines} lines of its own guidance, no @AGENTS.md import`) : "absent"}`,
+        `.agents/skills: ${r.agentsDir.skills ? "present" : "absent"}; .claude/skills: ${describeLink(r.claudeDir.skills)}`,
+        `.agents/rules: ${r.agentsDir.rules ? "present" : "absent"}; .claude/rules: ${describeLink(r.claudeDir.rules)}`,
+    ];
+    if (r.others.length > 0)
+        lines.push(`also present: ${r.others.join(", ")}`);
+    lines.push(`verdict: ${r.verdict === "portable" ? "portable (AGENTS.md canonical, Claude files import or link to it)" : r.verdict === "convertible" ? "convertible; --apply performs this plan in the working tree:" : "needs a hand merge before --apply:"}`);
+    for (const p of r.plan)
+        lines.push(`  - ${p}`);
+    for (const b of r.blockers)
+        lines.push(`  ⛔ ${b}`);
+    if (r.agentsMd.block !== "current")
+        lines.push(`  - the Catalyst block is ${r.agentsMd.block}: catalyst repo agents-block ${r.path} --write`);
+    return lines;
+}
+function checkoutRoot(args, sub) {
+    const [, path, ...extra] = positionals(args);
+    if (!path)
+        throw new UsageError(`repo ${sub} needs the checkout's path`);
+    if (extra.length > 0)
+        throw new UsageError(`repo ${sub} takes one path`);
+    const root = resolve(path);
+    if (!isDir(root))
+        throw new UsageError(`${path} is not a directory on this machine`);
+    return root;
+}
+export async function cmdRepo(args, ctx) {
+    const [sub] = positionals(args);
+    if (sub !== "agents-block" && sub !== "agent-setup")
+        throw new UsageError("repo needs agents-block <path> [--write] or agent-setup <path> [--apply] [--with-check]");
+    const root = checkoutRoot(args, sub);
+    const emit = (body, lines) => { if (args.json)
+        ctx.stdout(JSON.stringify(body));
+    else
+        for (const l of lines)
+            ctx.stdout(l); };
+    if (sub === "agents-block") {
+        if (flagBool(args, "apply") || flagBool(args, "with-check"))
+            throw new UsageError("--apply and --with-check belong to repo agent-setup");
+        const file = join(root, "AGENTS.md");
+        const before = existsSync(file) ? readFileSync(file, "utf8") : null;
+        const state = blockState(before);
+        if (!flagBool(args, "write")) {
+            const hint = state === "current" ? "nothing to do" : `run with --write to ${state === "absent" ? "create AGENTS.md with it" : state === "missing" ? "append it" : "bring it up to date"} (in the working tree; commit it on a branch and open a pull request)`;
+            emit({ path: root, agentsMd: before !== null, block: state, changed: false }, [`AGENTS.md: Catalyst block ${state} — ${hint}`]);
+            return state === "current" ? 0 : 1;
+        }
+        const after = withBlock(before);
+        const changed = after !== before;
+        if (changed)
+            writeFileSync(file, after);
+        emit({ path: root, agentsMd: true, block: "current", changed, was: state }, [
+            changed ? `AGENTS.md: Catalyst block ${state === "absent" ? "written to a new AGENTS.md" : state === "missing" ? "appended" : "updated in place"}; commit it on a branch and open a pull request` : "AGENTS.md: Catalyst block already current; nothing changed",
+        ]);
+        return 0;
+    }
+    if (flagBool(args, "write"))
+        throw new UsageError("--write belongs to repo agents-block");
+    const before = inspectRepo(root);
+    const applied = [];
+    if (flagBool(args, "apply"))
+        applied.push(...applyPlan(root, before));
+    if (flagBool(args, "with-check")) {
+        const dir = join(root, "scripts");
+        mkdirSync(dir, { recursive: true });
+        const target = join(dir, "agents-md-check.mjs");
+        const same = existsSync(target) && readFileSync(target, "utf8") === AGENTS_MD_CHECK_SCRIPT;
+        if (!same)
+            writeFileSync(target, AGENTS_MD_CHECK_SCRIPT, { mode: 0o755 });
+        applied.push(same ? "scripts/agents-md-check.mjs already current" : "wrote scripts/agents-md-check.mjs (run it in CI: node scripts/agents-md-check.mjs)");
+    }
+    const after = applied.length > 0 ? inspectRepo(root) : before;
+    emit({ ...after, applied }, [...(applied.length ? ["applied:", ...applied.map((a) => `  - ${a}`)] : []), ...reportLines(after)]);
+    return after.verdict === "portable" && after.agentsMd.block === "current" ? 0 : 1;
+}

package/dist/runtime-verb.js

@@ -1,4 +1,4 @@
-// runtime-verb.ts — CTC-2158, Tier 2. `catalyst-skills runtime status|install|path|uninstall`: the
+// runtime-verb.ts — CTC-2158, Tier 2. `catalyst runtime status|install|path|uninstall`: the
 // verb every unsupported-runtime message points at. It downloads the pinned Node named by
 // package.json's `catalystCloud.pinnedNode`, verifies it, and unpacks it under this CLI's own
 // cache — it never touches the machine's default Node and needs no admin rights.

package/dist/secret.js

@@ -1,4 +1,4 @@
-// secret.ts — `catalyst-skills secret set|import`: put a repository's secrets into the cloud from the
+// secret.ts — `catalyst secret set|import`: put a repository's secrets into the cloud from the
 // terminal, as the person who is logged in (CTC-3549). The cloud gates both on an admin or owner seat,
 // encrypts the value, and records who wrote it and where it came from, never the value itself.
 //
@@ -25,6 +25,7 @@ import { requireConfig } from "./config.js";
 import { CliError, UsageError } from "./errors.js";
 import { promptSecret, stdinIsTty } from "./prompt.js";
 import { apiClient } from "./transport.js";
+import { filterEnvFileNames } from "./env/parse-env.js";
 export const SECRETS_PATH = "/me/secrets";
 export const SECRETS_IMPORT_PATH = "/me/secrets/import";
 const NAME_RE = /^[A-Z][A-Z0-9_]*$/;
@@ -105,7 +106,19 @@ export async function cmdSecret(args, ctx, deps = {}) {
         throw new UsageError(sub === "set" ? "secret set takes one NAME" : "secret import takes one file (a .env file)");
     }
     const repo = requireRepo(args, sub);
-    return sub === "set" ? setOne(args, ctx, deps, rest[0], repo) : importFile(args, ctx, rest[0], repo);
+    return sub === "set" ? setOne(args, ctx, deps, rest[0], repo) : importFile(args, ctx, rest[0], repo, requestedNames(args));
+}
+function requestedNames(args) {
+    const raw = flagList(args, "names");
+    if (raw.length === 0)
+        return undefined;
+    const names = [...new Set(raw.flatMap((part) => part.split(",").map((name) => name.trim())).filter(Boolean))].sort();
+    if (names.length === 0)
+        throw new UsageError("--names needs one or more variable names");
+    const invalid = names.find((name) => !NAME_RE.test(name));
+    if (invalid !== undefined)
+        throw new UsageError(`--names includes an invalid env-style name: ${invalid}`);
+    return names;
 }
 async function setOne(args, ctx, deps, name, repo) {
     if (!NAME_RE.test(name))
@@ -150,7 +163,7 @@ async function setOne(args, ctx, deps, name, repo) {
         ctx.stdout(line);
     return 0;
 }
-async function importFile(args, ctx, file, repo) {
+async function importFile(args, ctx, file, repo, names) {
     if (flagString(args, "command") !== undefined)
         throw new UsageError("--command belongs to secret set");
     let text;
@@ -160,6 +173,9 @@ async function importFile(args, ctx, file, repo) {
     catch (err) {
         throw new UsageError(`could not read ${file}: ${err instanceof Error ? err.message : String(err)}`);
     }
+    const filtered = names === undefined ? { text, found: [] } : filterEnvFileNames(text, new Set(names));
+    if (names !== undefined)
+        text = filtered.text;
     const cfg = requireConfig(ctx);
     const rotate = flagList(args, "rotate");
     const res = await apiClient(cfg, ctx).postJson(SECRETS_IMPORT_PATH, { repo, text, rotateExisting: rotate, source: `import: ${basename(file)}` }, { accept: ACCEPT });
@@ -175,13 +191,18 @@ async function importFile(args, ctx, file, repo) {
     const rotated = body.rotated ?? [];
     const errors = body.errors ?? [];
     if (args.json) {
-        ctx.stdout(JSON.stringify({ repo, created, rotated, errors, declared: body.declared ?? null }));
+        ctx.stdout(JSON.stringify({ repo, created, rotated, errors, declared: body.declared ?? null, ...(names === undefined ? {} : { requested: names, notFoundInFile: names.filter((name) => !filtered.found.includes(name)) }) }));
         return errors.length > 0 ? 1 : 0;
     }
     const stored = created.length + rotated.length;
     ctx.stdout(stored === 0 ? `stored nothing for ${repo}` : `stored ${stored} for ${repo}: ${[...created, ...rotated].join(", ")}`);
     if (rotated.length > 0)
         ctx.stdout(`  replaced: ${rotated.join(", ")}`);
+    if (names !== undefined) {
+        const missing = names.filter((name) => !filtered.found.includes(name));
+        if (missing.length > 0)
+            ctx.stdout(`not found in ${basename(file)}: ${missing.join(", ")}`);
+    }
     for (const e of errors)
         ctx.stdout(`not stored: ${e.name} (${IMPORT_REASONS[e.reason] ?? e.reason})`);
     for (const line of renderDeclared(body.declared, repo))