agent-sdd 1.0.3

package/dist/features/install/domain/InstallPlan.js

@@ -0,0 +1,168 @@
+import { upsertManagedBlock } from "./ManagedBlock.js";
+import { mergeHooks } from "./SettingsMerge.js";
+export function installLayout(scope) {
+    if (scope === "project") {
+        return {
+            claudeMemoryRel: "CLAUDE.md",
+            codexMemoryRel: "AGENTS.md",
+            claudeImportPrefix: "@.claude/sdd/",
+            codexRulePrefix: ".codex/sdd/",
+            hookCommand: (_home, source) => `$CLAUDE_PROJECT_DIR/.claude/sdd/${source}`,
+        };
+    }
+    return {
+        claudeMemoryRel: ".claude/CLAUDE.md",
+        codexMemoryRel: ".codex/AGENTS.md",
+        claudeImportPrefix: "@sdd/",
+        codexRulePrefix: "~/.codex/sdd/",
+        hookCommand: (home, source) => homePath(home, `.claude/sdd/${source}`),
+    };
+}
+export function buildPlan(manifest, agent, sources, existing, home, scope = "user") {
+    const layout = installLayout(scope);
+    return agent === "claude"
+        ? planClaude(manifest, sources, existing, home, layout)
+        : planCodex(manifest, sources, existing, home, layout);
+}
+function planClaude(manifest, sources, existing, home, layout) {
+    const writes = [];
+    const actions = [];
+    const contextSources = [];
+    const desiredHooks = [];
+    for (const artifact of artifactsFor(manifest, "claude")) {
+        const relPath = artifact.kind === "skill"
+            ? `.claude/skills/${skillName(artifact)}/SKILL.md`
+            : `.claude/sdd/${artifact.source}`;
+        writes.push({
+            absPath: homePath(home, relPath),
+            content: content(sources, artifact.source),
+            executable: artifact.kind === "hook",
+        });
+        actions.push({
+            target: "claude",
+            kind: artifact.kind,
+            op: "copy",
+            path: relPath,
+            note: null,
+        });
+        if (artifact.kind === "context") {
+            contextSources.push(artifact.source);
+        }
+        if (artifact.kind === "hook" && artifact.event !== undefined) {
+            const event = artifact.event;
+            const command = layout.hookCommand(home, artifact.source);
+            desiredHooks.push({ matcher: event, command });
+            actions.push({
+                target: "claude",
+                kind: "hook",
+                op: "merge_hook",
+                path: ".claude/settings.json",
+                note: event,
+            });
+        }
+    }
+    const claudeMdRel = layout.claudeMemoryRel;
+    writes.push({
+        absPath: homePath(home, claudeMdRel),
+        content: upsertManagedBlock(existing.claudeMd, claudeImportBody(contextSources, layout.claudeImportPrefix)),
+        executable: false,
+    });
+    actions.push({
+        target: "claude",
+        kind: "managed_block",
+        op: "write_block",
+        path: claudeMdRel,
+        note: null,
+    });
+    if (desiredHooks.length > 0) {
+        writes.push({
+            absPath: homePath(home, ".claude/settings.json"),
+            content: mergeHooks(existing.settingsJson, desiredHooks),
+            executable: false,
+        });
+    }
+    return { writes, actions };
+}
+function planCodex(manifest, sources, existing, home, layout) {
+    const writes = [];
+    const actions = [];
+    const contextSources = [];
+    for (const artifact of artifactsFor(manifest, "codex")) {
+        const relPath = `.codex/sdd/${artifact.source}`;
+        writes.push({
+            absPath: homePath(home, relPath),
+            content: content(sources, artifact.source),
+            executable: false,
+        });
+        actions.push({
+            target: "codex",
+            kind: artifact.kind,
+            op: "copy",
+            path: relPath,
+            note: null,
+        });
+        if (artifact.kind === "context") {
+            contextSources.push(artifact.source);
+        }
+    }
+    for (const artifact of manifest.artifacts) {
+        if (artifact.kind === "hook" && !artifact.targets.includes("codex")) {
+            actions.push({
+                target: "codex",
+                kind: "hook",
+                op: "skip",
+                path: artifact.source,
+                note: "codex has no PreToolUse host",
+            });
+        }
+    }
+    const agentsMdRel = layout.codexMemoryRel;
+    writes.push({
+        absPath: homePath(home, agentsMdRel),
+        content: upsertManagedBlock(existing.agentsMd, codexReferenceBody(contextSources, layout.codexRulePrefix)),
+        executable: false,
+    });
+    actions.push({
+        target: "codex",
+        kind: "managed_block",
+        op: "write_block",
+        path: agentsMdRel,
+        note: null,
+    });
+    return { writes, actions };
+}
+function artifactsFor(manifest, agent) {
+    return manifest.artifacts.filter((a) => a.targets.includes(agent));
+}
+function content(sources, source) {
+    const value = sources.get(source);
+    if (value === undefined) {
+        throw new Error(`missing source content for ${source}`);
+    }
+    return value;
+}
+function claudeImportBody(contextSources, prefix) {
+    const imports = contextSources.map((s) => `${prefix}${s}`).join("\n");
+    return `SDD methodology rules (installed by \`sdd install\`). Loaded into context every session:\n\n${imports}`;
+}
+function codexReferenceBody(contextSources, prefix) {
+    const bullets = contextSources.map((s) => `- ${prefix}${s}`).join("\n");
+    return [
+        `SDD methodology rules installed by \`sdd install\` at ${prefix}.`,
+        "Read these before working in a project that carries .sdd/config.json:",
+        "",
+        bullets,
+        "",
+        `On-demand reference (read when needed): ${prefix}skills/spec-driven-development/SKILL.md, ${prefix}enforcement_registry.md`,
+    ].join("\n");
+}
+function skillName(artifact) {
+    if (artifact.skillName !== undefined) {
+        return artifact.skillName;
+    }
+    const segments = artifact.source.split("/");
+    return segments.length >= 2 ? segments[segments.length - 2] : segments[0];
+}
+export function homePath(home, relPath) {
+    return `${home.replace(/\/+$/, "")}/${relPath}`;
+}

package/dist/features/install/domain/InstallResult.d.ts

@@ -0,0 +1,23 @@
+import type { AgentTarget, InstallScope } from "./InstallTarget.js";
+export type ActionKind = "context" | "skill" | "reference" | "data" | "hook" | "managed_block";
+export type InstallOp = "copy" | "write_block" | "merge_hook" | "skip";
+export interface InstallAction {
+    target: AgentTarget;
+    kind: ActionKind;
+    op: InstallOp;
+    path: string;
+    note: string | null;
+}
+export type InstallFailureReason = "manifest-missing" | "manifest-invalid" | "artifact-missing";
+export type InstallOutcome = {
+    ok: true;
+    dryRun: boolean;
+    scope: InstallScope;
+    targets: AgentTarget[];
+    actions: InstallAction[];
+} | {
+    ok: false;
+    exitCode: 1;
+    reason: InstallFailureReason;
+    message: string;
+};

package/dist/features/install/domain/InstallResult.js

@@ -0,0 +1 @@
+export {};

package/dist/features/install/domain/InstallTarget.d.ts

@@ -0,0 +1,6 @@
+export type AgentTarget = "claude" | "codex";
+export type InstallTarget = AgentTarget | "all";
+export type InstallScope = "user" | "project";
+export declare const AGENT_TARGETS: readonly AgentTarget[];
+export declare function isInstallTarget(value: string): value is InstallTarget;
+export declare function agentsFor(target: InstallTarget): readonly AgentTarget[];

package/dist/features/install/domain/InstallTarget.js

@@ -0,0 +1,7 @@
+export const AGENT_TARGETS = ["claude", "codex"];
+export function isInstallTarget(value) {
+    return value === "all" || value === "claude" || value === "codex";
+}
+export function agentsFor(target) {
+    return target === "all" ? AGENT_TARGETS : [target];
+}

package/dist/features/install/domain/ManagedBlock.d.ts

@@ -0,0 +1,3 @@
+export declare const BLOCK_BEGIN = "<!-- BEGIN sdd-cli (managed by `sdd install`) -->";
+export declare const BLOCK_END = "<!-- END sdd-cli -->";
+export declare function upsertManagedBlock(existing: string | null, body: string): string;

package/dist/features/install/domain/ManagedBlock.js

@@ -0,0 +1,20 @@
+export const BLOCK_BEGIN = "<!-- BEGIN sdd-cli (managed by `sdd install`) -->";
+export const BLOCK_END = "<!-- END sdd-cli -->";
+export function upsertManagedBlock(existing, body) {
+    const block = `${BLOCK_BEGIN}\n${body}\n${BLOCK_END}`;
+    const current = existing ?? "";
+    const beginAt = current.indexOf(BLOCK_BEGIN);
+    const endAt = current.indexOf(BLOCK_END, beginAt + BLOCK_BEGIN.length);
+    if (beginAt !== -1 && endAt !== -1) {
+        const before = current.slice(0, beginAt);
+        const after = current.slice(endAt + BLOCK_END.length);
+        return ensureTrailingLf(`${before}${block}${after}`);
+    }
+    if (current.trim().length === 0) {
+        return `${block}\n`;
+    }
+    return `${current.replace(/\n+$/, "")}\n\n${block}\n`;
+}
+function ensureTrailingLf(value) {
+    return value.endsWith("\n") ? value : `${value}\n`;
+}

package/dist/features/install/domain/RuleManifest.d.ts

@@ -0,0 +1,17 @@
+import type { AgentTarget } from "./InstallTarget.js";
+export type ArtifactKind = "context" | "skill" | "reference" | "data" | "hook";
+export interface ManifestArtifact {
+    source: string;
+    kind: ArtifactKind;
+    targets: readonly AgentTarget[];
+    event?: string;
+    skillName?: string;
+}
+export interface RuleManifest {
+    formatVersion: 1;
+    artifacts: readonly ManifestArtifact[];
+}
+export declare class ManifestError extends Error {
+    constructor(message: string);
+}
+export declare function parseManifest(text: string): RuleManifest;

package/dist/features/install/domain/RuleManifest.js

@@ -0,0 +1,69 @@
+const ARTIFACT_KINDS = [
+    "context",
+    "skill",
+    "reference",
+    "data",
+    "hook",
+];
+export class ManifestError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ManifestError";
+    }
+}
+export function parseManifest(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (error) {
+        throw new ManifestError(`manifest is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isObject(raw)) {
+        throw new ManifestError("manifest must be a JSON object");
+    }
+    if (raw.format_version !== 1) {
+        throw new ManifestError("manifest format_version must be 1");
+    }
+    if (!Array.isArray(raw.artifacts)) {
+        throw new ManifestError("manifest artifacts must be an array");
+    }
+    const artifacts = raw.artifacts.map((entry, index) => parseArtifact(entry, index));
+    return { formatVersion: 1, artifacts };
+}
+function parseArtifact(entry, index) {
+    if (!isObject(entry)) {
+        throw new ManifestError(`artifact #${index} must be an object`);
+    }
+    const { source, kind, targets, event, skill_name: skillName } = entry;
+    if (typeof source !== "string" || source.length === 0) {
+        throw new ManifestError(`artifact #${index} has a missing or empty source`);
+    }
+    if (typeof kind !== "string" || !isArtifactKind(kind)) {
+        throw new ManifestError(`artifact ${source} has an unknown kind: ${String(kind)}`);
+    }
+    if (!Array.isArray(targets) ||
+        targets.length === 0 ||
+        !targets.every(isAgentTarget)) {
+        throw new ManifestError(`artifact ${source} must declare a non-empty targets array of claude|codex`);
+    }
+    if (kind === "hook" && (typeof event !== "string" || event.length === 0)) {
+        throw new ManifestError(`hook artifact ${source} must declare an event matcher`);
+    }
+    return {
+        source,
+        kind,
+        targets: targets,
+        event: typeof event === "string" ? event : undefined,
+        skillName: typeof skillName === "string" ? skillName : undefined,
+    };
+}
+function isArtifactKind(value) {
+    return ARTIFACT_KINDS.includes(value);
+}
+function isAgentTarget(value) {
+    return value === "claude" || value === "codex";
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/features/install/domain/SettingsMerge.d.ts

@@ -0,0 +1,5 @@
+export interface DesiredHook {
+    matcher: string;
+    command: string;
+}
+export declare function mergeHooks(existingText: string | null, desired: readonly DesiredHook[]): string;

package/dist/features/install/domain/SettingsMerge.js

@@ -0,0 +1,43 @@
+export function mergeHooks(existingText, desired) {
+    const settings = parseSettings(existingText);
+    const hooks = asObject(settings.hooks);
+    settings.hooks = hooks;
+    const preToolUse = asHookEntries(hooks.PreToolUse);
+    hooks.PreToolUse = preToolUse;
+    for (const want of desired) {
+        if (!hasHook(preToolUse, want)) {
+            preToolUse.push({
+                matcher: want.matcher,
+                hooks: [{ type: "command", command: want.command }],
+            });
+        }
+    }
+    return `${JSON.stringify(settings, null, 2)}\n`;
+}
+function hasHook(entries, want) {
+    return entries.some((entry) => entry.matcher === want.matcher &&
+        Array.isArray(entry.hooks) &&
+        entry.hooks.some((h) => h.command === want.command));
+}
+function parseSettings(text) {
+    if (text === null || text.trim().length === 0) {
+        return {};
+    }
+    const parsed = JSON.parse(text);
+    if (!isRecord(parsed)) {
+        throw new Error("settings.json must contain a JSON object");
+    }
+    return parsed;
+}
+function asObject(value) {
+    return isRecord(value) ? value : {};
+}
+function asHookEntries(value) {
+    return isHookEntryArray(value) ? value : [];
+}
+function isHookEntryArray(value) {
+    return Array.isArray(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/features/install/ports/inbound/InstallCommand.d.ts

@@ -0,0 +1,10 @@
+import type { CommandResult } from "../../../../shared/domain/CliOutput.js";
+import type { InstallScope, InstallTarget } from "../../domain/InstallTarget.js";
+export type { InstallScope, InstallTarget };
+export interface InstallOptions {
+    dryRun: boolean;
+    scope: InstallScope;
+}
+export interface InstallCommand {
+    execute(target: InstallTarget, options: InstallOptions, format: "json" | "human"): Promise<CommandResult>;
+}

package/dist/features/install/ports/inbound/InstallCommand.js

@@ -0,0 +1 @@
+export {};

package/dist/features/install/ports/outbound/InstallSource.d.ts

@@ -0,0 +1,4 @@
+export interface InstallSource {
+    manifestText(): Promise<string | null>;
+    readArtifact(source: string): Promise<string | null>;
+}

package/dist/features/install/ports/outbound/InstallSource.js

@@ -0,0 +1 @@
+export {};

package/dist/features/install/ports/outbound/InstallTargetFs.d.ts

@@ -0,0 +1,6 @@
+export interface InstallTargetFs {
+    homeRoot(): string;
+    projectRoot(): string;
+    readText(absPath: string): Promise<string | null>;
+    writeText(absPath: string, content: string, executable: boolean): Promise<void>;
+}

package/dist/features/install/ports/outbound/InstallTargetFs.js

@@ -0,0 +1 @@
+export {};

package/dist/features/lint/adapters/inbound/CliLintHandler.d.ts

@@ -0,0 +1,8 @@
+import { type CommandResult, type OutputFormat } from "../../../../shared/domain/CliOutput.js";
+import { type RunLintPorts } from "../../application/RunLint.js";
+import type { LintCommand } from "../../ports/inbound/LintCommand.js";
+export declare class CliLintHandler implements LintCommand {
+    private readonly ports;
+    constructor(ports: RunLintPorts);
+    execute(cwd: string, format: Exclude<OutputFormat, "yaml">): Promise<CommandResult>;
+}

package/dist/features/lint/adapters/inbound/CliLintHandler.js

@@ -0,0 +1,61 @@
+import { failed, ok, } from "../../../../shared/domain/CliOutput.js";
+import { CliFailure } from "../../../../shared/domain/Errors.js";
+import { runLint, } from "../../application/RunLint.js";
+export class CliLintHandler {
+    ports;
+    constructor(ports) {
+        this.ports = ports;
+    }
+    async execute(cwd, format) {
+        try {
+            const report = await runLint(cwd, this.ports);
+            if (format === "json") {
+                return jsonResult(report);
+            }
+            return humanResult(report);
+        }
+        catch (error) {
+            if (error instanceof CliFailure) {
+                return failed(error, format);
+            }
+            throw error;
+        }
+    }
+}
+function jsonResult(report) {
+    const body = JSON.stringify({
+        format_version: 1,
+        ok: report.errorCount === 0,
+        error_count: report.errorCount,
+        warn_count: report.warnCount,
+        diagnostics: report.diagnostics.map((d) => ({
+            severity: d.severity,
+            rule: d.rule,
+            file: d.file,
+            line: d.line ?? null,
+            message: d.message,
+        })),
+    });
+    if (report.errorCount === 0) {
+        return ok(body);
+    }
+    return { exitCode: 1, stdout: `${body}\n`, stderr: "" };
+}
+function humanResult(report) {
+    const lines = [];
+    for (const d of report.diagnostics) {
+        lines.push(formatDiagnostic(d));
+    }
+    lines.push("");
+    lines.push(`spec-lint: ${report.errorCount} error(s), ${report.warnCount} warning(s).`);
+    const stdout = `${lines.join("\n")}\n`;
+    if (report.errorCount === 0) {
+        return { exitCode: 0, stdout, stderr: "" };
+    }
+    return { exitCode: 1, stdout, stderr: "" };
+}
+function formatDiagnostic(d) {
+    const where = d.line !== undefined ? `${d.file}:${d.line}` : d.file;
+    const tag = d.severity === "error" ? "ERROR" : "warn";
+    return `[${tag}] ${where}  ${d.rule}: ${d.message}`;
+}

package/dist/features/lint/adapters/outbound/NodeLintFileReader.d.ts

@@ -0,0 +1,7 @@
+import { type SddConfig } from "../../../../shared/domain/Config.js";
+import type { LintConfigPort } from "../../ports/outbound/LintConfigPort.js";
+import type { LintFileReader, SpecFileEntry } from "../../ports/outbound/LintFileReader.js";
+export declare class NodeLintFileReader implements LintConfigPort, LintFileReader {
+    config(repoRoot: string): Promise<SddConfig>;
+    resolveSpecFiles(repoRoot: string, patterns: readonly string[]): Promise<SpecFileEntry[]>;
+}

package/dist/features/lint/adapters/outbound/NodeLintFileReader.js

@@ -0,0 +1,165 @@
+import { readFile, readdir, stat } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { configFromJson, } from "../../../../shared/domain/Config.js";
+import { configFailure } from "../../../../shared/domain/Errors.js";
+export class NodeLintFileReader {
+    async config(repoRoot) {
+        const configPath = join(repoRoot, ".sdd", "config.json");
+        const text = await readConfig(configPath);
+        return configFromJson(parseConfigJson(text, configPath), configPath);
+    }
+    async resolveSpecFiles(repoRoot, patterns) {
+        const matched = new Set();
+        for (const pattern of patterns) {
+            for (const abs of await expandGlob(repoRoot, pattern)) {
+                matched.add(abs);
+            }
+        }
+        const list = [...matched].sort();
+        const out = [];
+        for (const abs of list) {
+            const text = await readFile(abs, "utf8");
+            const rel = relative(repoRoot, abs);
+            out.push({ path: rel.split("\\").join("/"), content: text });
+        }
+        return out;
+    }
+}
+/*
+ * CST-006
+ * Minimal glob expander, no third-party glob library: keeps the runtime
+ * dependency surface to yaml only.
+ */
+async function expandGlob(repoRoot, pattern) {
+    const normalised = pattern.split("\\").join("/");
+    if (!hasGlob(normalised)) {
+        const abs = resolve(repoRoot, normalised);
+        return (await isFile(abs)) ? [abs] : [];
+    }
+    const segments = normalised.split("/");
+    const literalSegments = [];
+    let firstGlobIndex = -1;
+    for (let i = 0; i < segments.length; i++) {
+        if (hasGlob(segments[i])) {
+            firstGlobIndex = i;
+            break;
+        }
+        literalSegments.push(segments[i]);
+    }
+    const baseDir = resolve(repoRoot, ...literalSegments);
+    const remaining = segments.slice(firstGlobIndex);
+    const out = [];
+    await walkAndMatch(baseDir, remaining, out);
+    return out;
+}
+async function walkAndMatch(dir, remaining, acc) {
+    if (remaining.length === 0) {
+        return;
+    }
+    const head = remaining[0];
+    const rest = remaining.slice(1);
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    if (head === "**") {
+        /*
+         * Match zero or more directory levels: keep `**` in the remaining set
+         * until a non-** segment matches.
+         */
+        if (rest.length === 0) {
+            /* `**` as the last segment matches every file under dir. */
+            for (const entry of entries) {
+                const abs = join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    await walkAndMatch(abs, ["**"], acc);
+                }
+                else if (entry.isFile()) {
+                    acc.push(abs);
+                }
+            }
+            return;
+        }
+        /* Try to match without consuming a directory level (descend keeping **). */
+        for (const entry of entries) {
+            const abs = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walkAndMatch(abs, remaining, acc);
+            }
+        }
+        /* Try to consume `**` here and match the next segment. */
+        await walkAndMatch(dir, rest, acc);
+        return;
+    }
+    for (const entry of entries) {
+        if (!matchSegment(head, entry.name)) {
+            continue;
+        }
+        const abs = join(dir, entry.name);
+        if (rest.length === 0) {
+            if (entry.isFile()) {
+                acc.push(abs);
+            }
+            continue;
+        }
+        if (entry.isDirectory()) {
+            await walkAndMatch(abs, rest, acc);
+        }
+    }
+}
+function matchSegment(pattern, name) {
+    if (!hasGlob(pattern)) {
+        return pattern === name;
+    }
+    /*
+     * Translate the segment pattern to a regex; supports `*` (any chars except /),
+     * `?` (single char), and literal characters.
+     */
+    const re = new RegExp(`^${pattern
+        .split("")
+        .map((c) => {
+        if (c === "*") {
+            return "[^/]*";
+        }
+        if (c === "?") {
+            return "[^/]";
+        }
+        return c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    })
+        .join("")}$`);
+    return re.test(name);
+}
+function hasGlob(value) {
+    return /[*?[\]]/.test(value);
+}
+async function isFile(abs) {
+    try {
+        const s = await stat(abs);
+        return s.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function readConfig(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        throw configFailure("config-missing", ".sdd/config.json is missing or unreadable", errorMessage(error), path);
+    }
+}
+function parseConfigJson(text, path) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw configFailure("config-invalid", ".sdd/config.json is not valid JSON", errorMessage(error), path);
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/features/lint/application/RunLint.d.ts

@@ -0,0 +1,10 @@
+import { type Diagnostic, type LintReport } from "../domain/Diagnostic.js";
+export type { Diagnostic, LintReport };
+import type { LintConfigPort } from "../ports/outbound/LintConfigPort.js";
+import type { LintFileReader } from "../ports/outbound/LintFileReader.js";
+export interface RunLintPorts {
+    config: LintConfigPort;
+    files: LintFileReader;
+}
+export declare function runLint(cwd: string, ports: RunLintPorts): Promise<LintReport>;
+export declare function diagnosticsByFile(report: LintReport): Map<string, Diagnostic[]>;