@rsaglobaltech/specgate 0.8.1

package/dist/scripts/cli/commands/config/ConfigSetCommand.js

@@ -0,0 +1,166 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigSetCommand = exports.KEYS = exports.CONFIG_FILE = exports.CONFIG_DIR = void 0;
+exports.configPath = configPath;
+exports.read = read;
+exports.write = write;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const diagnostics_1 = require("../../../lib/diagnostics");
+const agent_1 = require("../../../lib/agent");
+const command_1 = require("../../../lib/command");
+exports.CONFIG_DIR = ".csda";
+exports.CONFIG_FILE = "config.json";
+exports.KEYS = {
+    profile: {
+        values: ["core", "full"],
+        describe: "Which commands `specgate --help` lists by default.",
+    },
+    language: {
+        values: null,
+        describe: "Language for generated prose. Technical terms stay in English.",
+    },
+};
+function configPath(projectDir) {
+    return path.join(projectDir, exports.CONFIG_DIR, exports.CONFIG_FILE);
+}
+function read(projectDir) {
+    try {
+        return JSON.parse(fs.readFileSync(configPath(projectDir), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function write(projectDir, config) {
+    const file = configPath(projectDir);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+    return file;
+}
+function usage() {
+    const keys = Object.entries(exports.KEYS)
+        .map(([k, v]) => {
+        const allowed = v.values ? ` (${v.values.join(" | ")})` : "";
+        return `    ${k}${allowed}\n      ${v.describe}`;
+    })
+        .join("\n");
+    process.stdout.write("Usage:\n" +
+        "  specgate config set <key> <value>\n" +
+        "  specgate config get <key>\n" +
+        "  specgate config list\n\n" +
+        `Keys:\n${keys}\n\n` +
+        `Stored in ${exports.CONFIG_DIR}/${exports.CONFIG_FILE}. Commit it to share the setting.\n`);
+}
+class ConfigSetCommand extends command_1.BaseCommand {
+    execute() {
+        const argv = this.args;
+        const io = (0, agent_1.agentIo)((0, agent_1.wantsJson)(argv));
+        const NULL_SHAPE = { config: null };
+        const args = argv.filter((a) => a !== "--json");
+        if (args.includes("--help") || args.includes("-h")) {
+            usage();
+            process.exit(agent_1.EXIT.OK);
+        }
+        let projectDir = ".";
+        const positional = [];
+        for (let i = 0; i < args.length; i++) {
+            if (args[i] === "--project-dir" && args[i + 1])
+                projectDir = args[++i];
+            else if (!args[i].startsWith("-"))
+                positional.push(args[i]);
+        }
+        const [action, key, ...rest] = positional;
+        if (action === "list" || (!action && !key)) {
+            const config = read(projectDir);
+            io.emit({ config }, () => {
+                const entries = Object.entries(config);
+                if (entries.length === 0) {
+                    process.stdout.write("  (no settings — everything is at its default)\n");
+                    return;
+                }
+                for (const [k, v] of entries)
+                    process.stdout.write(`  ${k} = ${v}\n`);
+            });
+            return;
+        }
+        if (!exports.KEYS[key]) {
+            io.usage(NULL_SHAPE, [
+                (0, diagnostics_1.error)("config_key_unknown", `Unknown setting: ${key || "(none)"}`, {
+                    target: key,
+                    fix: `Known settings: ${Object.keys(exports.KEYS).join(", ")}.`,
+                }),
+            ]);
+        }
+        if (action === "get") {
+            const config = read(projectDir);
+            io.emit({ config: { [key]: config[key] ?? null } }, () => process.stdout.write(`  ${key} = ${config[key] ?? "(default)"}\n`));
+            return;
+        }
+        if (action !== "set") {
+            io.usage(NULL_SHAPE, [
+                (0, diagnostics_1.error)("config_action_unknown", `Unknown action: ${action || "(none)"}`, {
+                    target: action,
+                    fix: "Use one of: set, get, list.",
+                }),
+            ]);
+        }
+        const value = rest[0];
+        if (value === undefined) {
+            io.usage(NULL_SHAPE, [
+                (0, diagnostics_1.error)("config_value_required", `No value given for ${key}.`, {
+                    fix: `specgate config set ${key} <value>`,
+                }),
+            ]);
+        }
+        const allowed = exports.KEYS[key].values;
+        if (allowed && !allowed.includes(value)) {
+            io.usage(NULL_SHAPE, [
+                (0, diagnostics_1.error)("config_value_invalid", `${value} is not a valid ${key}.`, {
+                    target: value,
+                    fix: `Use one of: ${allowed.join(", ")}.`,
+                }),
+            ]);
+        }
+        const config = read(projectDir);
+        config[key] = value;
+        const file = write(projectDir, config);
+        io.emit({ config }, () => process.stdout.write(`  ✔  ${key} = ${value}\n     ${path.relative(process.cwd(), file) || file}\n`));
+        process.exit(agent_1.EXIT.OK);
+    }
+}
+exports.ConfigSetCommand = ConfigSetCommand;
+//# sourceMappingURL=ConfigSetCommand.js.map

package/dist/scripts/cli/commands/config/ConfigSetCommand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConfigSetCommand.js","sourceRoot":"","sources":["../../../../../scripts/cli/commands/config/ConfigSetCommand.ts"],"names":[],"mappings":"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"}

package/dist/scripts/cli/commands/config/GenAgentContractCommand.js

@@ -0,0 +1,212 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GenAgentContractCommand = exports.COMMANDS = exports.OUTPUT = void 0;
+exports.harvestCodes = harvestCodes;
+exports.render = render;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const command_1 = require("../../../lib/command");
+const agent_1 = require("../../../lib/agent");
+const surface_1 = require("../../../lib/surface");
+function repoRoot() {
+    let dir = __dirname;
+    while (!fs.existsSync(path.join(dir, "package.json"))) {
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            throw new Error("package.json not found above " + __dirname);
+        dir = parent;
+    }
+    return dir;
+}
+const ROOT = repoRoot();
+exports.OUTPUT = path.join(ROOT, "docs/specs/agent-contract.md");
+exports.COMMANDS = (0, surface_1.jsonContractRows)();
+const SOURCE_GLOBS = [
+    "scripts/validate_specs.ts",
+    "scripts/doctor.ts",
+    "scripts/done.ts",
+    "scripts/cli/commands/change/ChangeCommand.ts",
+    "packages/core/src/application/ValidateChangeUseCase.ts",
+    "packages/core/src/domain/DeltaSpec.ts",
+    "packages/core/src/application/ArchiveChangeUseCase.ts",
+    "scripts/change/instructions.ts",
+    "packages/core/src/application/CheckAgainstLockUseCase.ts",
+    "scripts/specops/against_lock.ts",
+    "scripts/cli/commands/specops/ContributeCommand.ts",
+];
+function harvestCodes() {
+    const byArea = new Map();
+    for (const rel of SOURCE_GLOBS) {
+        const file = path.join(ROOT, rel);
+        // A listed file that has moved would silently drop its codes from the
+        // contract, so say so rather than quietly harvesting less.
+        if (!fs.existsSync(file)) {
+            throw new Error(`Agent contract source not found: ${rel}. Update SOURCE_GLOBS if the file moved.`);
+        }
+        const source = fs.readFileSync(file, "utf8");
+        const codes = new Set();
+        for (const m of source.matchAll(/\b(?:error|warning|info|fail)\(\s*"([a-z][a-z0-9_]*)"/g)) {
+            codes.add(m[1]);
+        }
+        for (const m of source.matchAll(/\bdiagnostic\(\s*[^,]+,\s*"([a-z][a-z0-9_]*)"/g)) {
+            codes.add(m[1]);
+        }
+        for (const m of source.matchAll(/\b(?:error|warning)\(\s*`([a-z][a-z0-9_]*)\$\{/g)) {
+            codes.add(`${m[1]}*`);
+        }
+        if (codes.size > 0)
+            byArea.set(rel, [...codes].sort());
+    }
+    return byArea;
+}
+function table(rows, headers) {
+    const head = `| ${headers.join(" | ")} |`;
+    const sep = `|${headers.map(() => "---").join("|")}|`;
+    return [head, sep, ...rows.map((r) => `| ${r.join(" | ")} |`)].join("\n");
+}
+function render() {
+    const codes = harvestCodes();
+    const codeRows = [];
+    for (const [file, list] of codes) {
+        for (const code of list)
+            codeRows.push([`\`${code}\``, `\`${file}\``]);
+    }
+    return `# The agent contract
+
+<!-- GENERATED by scripts/gen_agent_contract.ts — do not edit by hand.
+     Run \`npm run docs:agent-contract\` after changing a command's JSON shape or
+     adding a diagnostic code. tests/unit/agent-contract.test.ts fails when this
+     file is stale. -->
+
+How a machine drives this CLI. The rules are fixed by
+[ADR-0017](adr/0017-agent-json-contract.md); this document is generated from the
+source so it cannot drift from it.
+
+## The rules
+
+1. **One JSON document per invocation.** In \`--json\` mode stdout carries exactly
+   one JSON document. Prose, progress and warnings go to stderr, so
+   \`cmd --json 2>/dev/null | jq .\` always parses.
+2. **One diagnostic envelope**, everywhere:
+
+   \`\`\`json
+   {
+     "severity": "error" | "warning" | "info",
+     "code": "snake_case_stable_string",
+     "message": "human sentence",
+     "target": "the thing at fault (optional)",
+     "fix": "one actionable sentence or command (optional)",
+     "file": "relative/path.md (optional)",
+     "line": 42
+   }
+   \`\`\`
+
+   Branch on \`code\`, never on \`message\`. \`message\` is prose and may be reworded;
+   \`code\` is the published surface.
+3. **Failure carries the command's null-shape.** A failure prints
+   \`{ ...nullShape, "status": [diagnostic] }\` and exits 1 — never bare stderr,
+   never a partial document. A consumer never has to tell "it failed" apart from
+   "it printed nothing".
+4. **camelCase everywhere** in command output. (The on-disk formats are not
+   command output: \`pack.yaml\` keeps \`schema_version\` and \`.specops.lock\` keeps
+   \`pack_id\`.)
+5. **\`--json\` and \`--format json\` are the same flag.** The second spelling
+   predates the contract and keeps working.
+
+## Exit codes
+
+${table([
+        ["Success, including advisory warnings", `\`${agent_1.EXIT.OK}\``],
+        ["Command failure — one JSON document with `status`", `\`${agent_1.EXIT.FAILURE}\``],
+        ["Gate failure (`validate`, `doctor`, `change validate`)", `\`${agent_1.EXIT.FAILURE}\``],
+        ["Usage error — unknown flag, missing or malformed argument", `\`${agent_1.EXIT.USAGE}\``],
+        ["Required script missing (a broken installation)", `\`${agent_1.EXIT.MISSING_PREREQUISITE}\``],
+        ["Cancelled by the user", `\`${agent_1.EXIT.CANCELLED}\``],
+    ], ["Situation", "Exit"])}
+
+A gate command exits ${agent_1.EXIT.FAILURE} when it *finds* something, which is not the
+same as failing to run. The \`status\` array tells the two apart: a gate that could
+not run reports an \`error\` about itself.
+
+## Commands
+
+${table(exports.COMMANDS.map((c) => [
+        `\`specgate ${c.command}\``,
+        `\`${c.nullShapeKey}\``,
+        c.gate ? "yes" : "no",
+    ]), ["Command", "Document key", "Gate"])}
+
+The document key is what the payload carries on success and what is set to
+\`null\` on failure. Every document also carries \`status\`: an array of
+diagnostics, empty when there is nothing to report.
+
+## Diagnostic codes
+
+Harvested from the source. A trailing \`*\` marks a family whose suffix is
+computed — \`strict_tdd_*\` covers \`strict_tdd_1\` through \`strict_tdd_3\`.
+
+${table(codeRows, ["Code", "Emitted by"])}
+
+## Worked example
+
+\`\`\`bash
+specgate change instructions specs --json 2>/dev/null | jq -r '.instructions.rules[]'
+\`\`\`
+
+An agent that reads \`fix\` self-corrects; one that reads only \`message\` retries
+the same mistake. That is why a check without a \`fix\` is treated as unfinished.
+`;
+}
+class GenAgentContractCommand extends command_1.BaseCommand {
+    execute() {
+        const check = this.args.includes("--check");
+        const rendered = render();
+        if (check) {
+            const current = fs.existsSync(exports.OUTPUT) ? fs.readFileSync(exports.OUTPUT, "utf8") : "";
+            if (current !== rendered) {
+                process.stderr.write("docs/specs/agent-contract.md is stale. Run: npm run docs:agent-contract\n");
+                process.exit(agent_1.EXIT.FAILURE);
+            }
+            process.stdout.write("agent-contract.md is up to date\n");
+            return;
+        }
+        fs.mkdirSync(path.dirname(exports.OUTPUT), { recursive: true });
+        fs.writeFileSync(exports.OUTPUT, rendered, "utf8");
+        process.stdout.write(`Wrote ${path.relative(ROOT, exports.OUTPUT)}\n`);
+    }
+}
+exports.GenAgentContractCommand = GenAgentContractCommand;
+//# sourceMappingURL=GenAgentContractCommand.js.map

package/dist/scripts/cli/commands/config/GenAgentContractCommand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GenAgentContractCommand.js","sourceRoot":"","sources":["../../../../../scripts/cli/commands/config/GenAgentContractCommand.ts"],"names":[],"mappings":"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"}