@sdd-method/author-cli 0.0.0-stage → 0.1.0

package/dist/lib/api-surface/detect.js

@@ -0,0 +1,25 @@
+import { basename } from "node:path";
+export function detectStack(files, signals = { hasSpringController: false }) {
+    const names = files.map((f) => basename(f).toLowerCase());
+    const has = (pred) => names.some(pred);
+    const hasJavaBuild = has((n) => n === "pom.xml" || n === "build.gradle");
+    // (1) A Spring service ships as a Spring service even with a bundled IaC/serverless wrapper.
+    if (hasJavaBuild && signals.hasSpringController)
+        return "java-spring";
+    const hasServerless = has((n) => n === "serverless.yml" || n === "serverless.yaml");
+    if (hasServerless)
+        return "node-serverless";
+    const hasTerraform = files.some((f) => f.toLowerCase().endsWith(".tf"));
+    if (hasTerraform)
+        return "terraform";
+    const hasManifest = hasJavaBuild || has((n) => n === "package.json");
+    if (hasManifest)
+        return "library";
+    return "unknown";
+}
+/** Class/type-level annotation that marks a Spring web controller. */
+const SPRING_CONTROLLER_RE = /@(Rest)?Controller\b|@RequestMapping\b/;
+export function fileLooksLikeSpringController(source) {
+    return SPRING_CONTROLLER_RE.test(source);
+}
+//# sourceMappingURL=detect.js.map

package/dist/lib/api-surface/emit.js

@@ -0,0 +1,109 @@
+import { stringify as stringifyYaml } from "yaml";
+// Serialisers for an ApiSurface. `toYaml` produces the contracts/api-surface.yaml document (keys in a
+// stable, human-readable order; empty blocks omitted so non-endpoint stacks don't carry noise).
+// `toMarkdownBlock` produces the `## External Interfaces` + `## Dependency Graph` documentation block
+// the reverse rubric reads.
+export function toYaml(surface) {
+    // Build an ordered plain object so the YAML key order is deterministic and reads top-down.
+    const doc = {
+        repo: surface.repo,
+        profile: surface.profile,
+        component_type: surface.component_type,
+        domain: surface.domain,
+        stack: surface.stack,
+    };
+    if (surface.source_snapshot)
+        doc["source_snapshot"] = surface.source_snapshot;
+    doc["generated_by"] = surface.generated_by;
+    if (surface.endpoints.length > 0) {
+        doc["endpoints"] = surface.endpoints.map((e) => ({
+            method: e.method,
+            path: e.path,
+            auth: e.auth,
+            handler: e.handler,
+        }));
+    }
+    doc["dependencies"] = {
+        downstream: surface.dependencies.downstream.map((d) => ({
+            target: d.target,
+            kind: d.kind,
+            detail: d.detail,
+            load_bearing: d.load_bearing,
+        })),
+        upstream: surface.dependencies.upstream,
+    };
+    if (surface.external_contracts.length > 0) {
+        doc["external_contracts"] = surface.external_contracts;
+    }
+    const deployment = {
+        runtime: surface.deployment.runtime,
+        shared_infra: surface.deployment.shared_infra,
+    };
+    if (surface.deployment.provisioned_resources && surface.deployment.provisioned_resources.length > 0) {
+        deployment["provisioned_resources"] = surface.deployment.provisioned_resources;
+    }
+    if (surface.deployment.notes && surface.deployment.notes.length > 0) {
+        deployment["notes"] = surface.deployment.notes;
+    }
+    doc["deployment"] = deployment;
+    if (surface.public_api) {
+        const pub = {};
+        if (surface.public_api.package_name)
+            pub["package_name"] = surface.public_api.package_name;
+        pub["exports"] = surface.public_api.exports;
+        doc["public_api"] = pub;
+    }
+    doc["consumed_by"] = surface.consumed_by;
+    return stringifyYaml(doc, { lineWidth: 0 });
+}
+export function toMarkdownBlock(surface) {
+    const lines = [];
+    lines.push("## External Interfaces");
+    lines.push("");
+    if (surface.endpoints.length > 0) {
+        lines.push("| Method | Path | Auth | Handler |");
+        lines.push("| --- | --- | --- | --- |");
+        for (const e of surface.endpoints) {
+            lines.push(`| ${e.method} | ${e.path} | ${e.auth} | ${e.handler} |`);
+        }
+    }
+    else {
+        lines.push(`_No HTTP endpoints (${surface.stack} stack)._`);
+    }
+    lines.push("");
+    lines.push("## Dependency Graph");
+    lines.push("");
+    const down = surface.dependencies.downstream;
+    if (down.length > 0) {
+        lines.push("**Downstream:**");
+        lines.push("");
+        lines.push("| Target | Kind | Detail | Load-bearing |");
+        lines.push("| --- | --- | --- | --- |");
+        for (const d of down) {
+            lines.push(`| ${d.target} | ${d.kind} | ${d.detail} | ${d.load_bearing ? "yes" : "no"} |`);
+        }
+        lines.push("");
+    }
+    const up = surface.dependencies.upstream;
+    lines.push(`**Upstream:** ${up.length > 0 ? up.join(", ") : "_unknown_"}`);
+    lines.push("");
+    if (surface.external_contracts.length > 0) {
+        lines.push("**External contracts:** " + surface.external_contracts.join(", "));
+        lines.push("");
+    }
+    lines.push("## Deployment");
+    lines.push("");
+    lines.push(`- Runtime: ${surface.deployment.runtime || "_unknown_"}`);
+    if (surface.deployment.shared_infra.length > 0) {
+        lines.push(`- Shared infra: ${surface.deployment.shared_infra.join(", ")}`);
+    }
+    if (surface.deployment.provisioned_resources && surface.deployment.provisioned_resources.length > 0) {
+        const summary = surface.deployment.provisioned_resources
+            .map((r) => `${r.type} ×${r.count}`)
+            .join(", ");
+        lines.push(`- Provisioned: ${summary}`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+//# sourceMappingURL=emit.js.map

package/dist/lib/api-surface/file-set.js

@@ -0,0 +1,43 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+export function diskFileSet(root, files) {
+    const cache = new Map();
+    return {
+        root,
+        files,
+        async read(relPath) {
+            const cached = cache.get(relPath);
+            if (cached !== undefined)
+                return cached;
+            let content = "";
+            try {
+                content = await readFile(join(root, relPath), "utf-8");
+            }
+            catch {
+                content = "";
+            }
+            cache.set(relPath, content);
+            return content;
+        },
+    };
+}
+/** Build a FileSet from an in-memory `{ path: content }` map — for tests. */
+export function inMemoryFileSet(entries, root = "/virtual") {
+    return {
+        root,
+        files: Object.keys(entries),
+        async read(relPath) {
+            return entries[relPath] ?? "";
+        },
+    };
+}
+/** First file (by suffix match, case-insensitive) or null. */
+export function findBySuffix(files, suffix) {
+    const lower = suffix.toLowerCase();
+    return files.find((f) => f.toLowerCase().endsWith(lower)) ?? null;
+}
+export function allBySuffix(files, suffix) {
+    const lower = suffix.toLowerCase();
+    return files.filter((f) => f.toLowerCase().endsWith(lower));
+}
+//# sourceMappingURL=file-set.js.map

package/dist/lib/api-surface/index.js

@@ -0,0 +1,134 @@
+import { readdir } from "node:fs/promises";
+import { basename, join, relative } from "node:path";
+import { getSddCliVersion } from "../package-version.js";
+import { analyzeLibrary } from "./analyzers/library.js";
+import { analyzeServerless } from "./analyzers/serverless.js";
+import { analyzeSpring } from "./analyzers/spring.js";
+import { analyzeTerraform } from "./analyzers/terraform.js";
+import { detectStack, fileLooksLikeSpringController } from "./detect.js";
+import { diskFileSet } from "./file-set.js";
+import { emptyDependencies, emptyDeployment, } from "./types.js";
+// Directories never worth walking — build output, vcs, deps.
+const SKIP_DIRS = new Set([
+    ".git",
+    "node_modules",
+    "target",
+    "dist",
+    "build",
+    ".terraform",
+    ".gradle",
+    ".idea",
+    ".mvn",
+]);
+export async function analyzeRepo(opts) {
+    const files = await walkRepo(opts.source);
+    const fileSet = diskFileSet(opts.source, files);
+    const stack = await detect(fileSet);
+    const analyzed = await dispatch(stack, fileSet);
+    const { repo, snapshot } = resolveRepoIdentity(opts.source, opts.repo);
+    const result = {
+        repo,
+        profile: opts.profile ?? "reverse",
+        component_type: analyzed.component_type,
+        domain: opts.domain ?? "",
+        stack: analyzed.stack,
+        ...(snapshot ? { source_snapshot: snapshot } : {}),
+        generated_by: `sdd-cli api-surface v${getSddCliVersion()}`,
+        endpoints: analyzed.endpoints,
+        dependencies: analyzed.dependencies,
+        external_contracts: analyzed.external_contracts,
+        deployment: analyzed.deployment,
+        ...(analyzed.public_api ? { public_api: analyzed.public_api } : {}),
+        consumed_by: analyzed.consumed_by ?? [],
+    };
+    return result;
+}
+async function detect(fileSet) {
+    // A Java build may be wrapped in a deployment layer — a bundled `terraform/` subdir or a
+    // `serverless.yml` for Lambda packaging. Scan for a Spring controller whenever a Java build
+    // is present (not only when path-only detection already says "library"), so the wrapper does
+    // not mask a real Spring service. detectStack then gives java-spring precedence (W1.1 fix).
+    const hasJavaBuild = fileSet.files.some((f) => {
+        const b = f.split("/").pop()?.toLowerCase();
+        return b === "pom.xml" || b === "build.gradle";
+    });
+    if (!hasJavaBuild)
+        return detectStack(fileSet.files);
+    // A Java build is present — decide spring-vs-library by looking for a controller.
+    const javaFiles = fileSet.files.filter((f) => f.toLowerCase().endsWith(".java") && !/(^|\/)(target|build)\//.test(f));
+    let hasSpringController = false;
+    for (const f of javaFiles) {
+        const src = await fileSet.read(f);
+        if (fileLooksLikeSpringController(src) && /@(Rest)?Controller\b/.test(src)) {
+            hasSpringController = true;
+            break;
+        }
+    }
+    return detectStack(fileSet.files, { hasSpringController });
+}
+async function dispatch(stack, fileSet) {
+    switch (stack) {
+        case "node-serverless":
+            return analyzeServerless(fileSet);
+        case "java-spring":
+            return analyzeSpring(fileSet);
+        case "terraform":
+            return analyzeTerraform(fileSet);
+        case "library":
+            return analyzeLibrary(fileSet);
+        case "unknown":
+            return {
+                stack: "unknown",
+                component_type: "unknown",
+                endpoints: [],
+                dependencies: emptyDependencies(),
+                external_contracts: [],
+                deployment: emptyDeployment(),
+            };
+    }
+}
+/**
+ * Derive `{ repo, snapshot }` from the source dir name. A `<repo>-master@<sha>` directory yields the
+ * repo slug and the full `<repo>-master@<sha>` snapshot string. An explicit `--repo` overrides the slug
+ * but the snapshot is still taken from the dir name when it matches the pattern.
+ */
+export function resolveRepoIdentity(source, repoOverride) {
+    const dir = basename(source.replace(/\/+$/, ""));
+    const m = dir.match(/^(.+?)-master@([0-9a-f]+)$/i);
+    if (m) {
+        return { repo: repoOverride ?? m[1], snapshot: dir };
+    }
+    return { repo: repoOverride ?? dir };
+}
+async function walkRepo(root) {
+    const out = [];
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith(".") && SKIP_DIRS.has(entry.name))
+                continue;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (SKIP_DIRS.has(entry.name))
+                    continue;
+                await walk(full);
+            }
+            else if (entry.isFile()) {
+                out.push(toPosix(relative(root, full)));
+            }
+        }
+    }
+    await walk(root);
+    out.sort();
+    return out;
+}
+function toPosix(p) {
+    return p.split("\\").join("/");
+}
+//# sourceMappingURL=index.js.map

package/dist/lib/api-surface/types.js

@@ -0,0 +1,17 @@
+// Result interfaces for `sdd-cli api-surface` (W1). The shape EXTENDS the existing
+// `contracts/api-surface.yaml` keys (repo, profile, component_type, domain, public_api.exports,
+// consumed_by) so emitted files round-trip with hand-authored ones — it never drops those keys.
+//
+// The four blocks below map 1:1 to the reverse `repo-doc-quality` rubric requirement for
+// `interface_and_dependency_coverage = 2`:
+//   endpoints          → item 1 (all endpoints with method+path+auth)
+//   dependencies       → item 2 (explicit upstream/downstream graph)
+//   external_contracts → item 3 (external contracts referenced)
+//   deployment         → item 4 (deployment coupling: shared infra/db/queue)
+export function emptyDependencies() {
+    return { downstream: [], upstream: [] };
+}
+export function emptyDeployment() {
+    return { runtime: "", shared_infra: [] };
+}
+//# sourceMappingURL=types.js.map

package/dist/lib/briefing/index.js

@@ -0,0 +1,13 @@
+/**
+ * Public facade for the briefing layer (ADR 0148).
+ *
+ * `agent-instructions.md` is the harness-neutral canonical briefing
+ * (fully method-managed; sync overwrites unconditionally). Harness
+ * wrappers (`CLAUDE.md`, `AGENTS.md`, …) are thin pointers with a
+ * `<!-- method-managed: begin/end -->` block at the top; adopter
+ * content below survives sync via the existing `writeMarkedBlockFile`
+ * machinery.
+ */
+export { AGENT_INSTRUCTIONS_REL_PATH, BRIEFING_TEMPLATE_ROOT, WRAPPER_BLOCK_BEGIN, WRAPPER_BLOCK_END, extractWrapperBlock, findUnresolvedPlaceholders, AGENTS_POINTER, briefingWrappers, harnessWrapperOutputPath, renderAgentInstructions, renderHarnessWrapper, renderWrapper, splitWrapperTemplate, substitute, } from "./render.js";
+export { resolveBriefingVariables } from "./variables.js";
+//# sourceMappingURL=index.js.map

package/dist/lib/briefing/render.js

@@ -0,0 +1,132 @@
+/**
+ * Renderer for the briefing-layer templates per ADR 0148 + Phase 4 of
+ * `adopt-agent-instructions-briefing-layer.md`.
+ *
+ * Templates ship via the method baseline bundle and land at
+ * `<target>/orchestration/templates/briefing/...` after sync's
+ * `copyManagedFiles` step. Both `sdd-cli init` and `sdd-cli sync` read
+ * the on-disk templates and substitute the four canonical variables.
+ *
+ * Substitution is a deliberate Handlebars *subset* — `{{var}}` only,
+ * no helpers / conditionals / partials. Keeps the runtime-dep
+ * allowlist clean (no Handlebars package) and matches the template
+ * shapes shipped upstream.
+ */
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+export const BRIEFING_TEMPLATE_ROOT = "orchestration/templates/briefing";
+export const AGENT_INSTRUCTIONS_REL_PATH = "agent-instructions.md";
+const HARNESS_WRAPPER_TEMPLATE = {
+    "claude-code": {
+        templateRel: "claude-code/CLAUDE.md.hbs",
+        outputRel: "CLAUDE.md",
+    },
+};
+/** Output filename per harness — `CLAUDE.md`. */
+export function harnessWrapperOutputPath(harness) {
+    return HARNESS_WRAPPER_TEMPLATE[harness].outputRel;
+}
+/**
+ * The AGENTS.md pointer (M-ADR 0220 §4.6): a few lines directing any agent tool that reads a root
+ * AGENTS.md to agent-instructions.md. Written for every SDD and code repository with no flag, and
+ * rendered and refreshed exactly as the CLAUDE.md wrapper is. A pointer, not support for another
+ * harness. Relative to the briefing template root; code repositories read it under code-repo/.
+ */
+export const AGENTS_POINTER = { templateRel: "AGENTS.md.hbs", outputRel: "AGENTS.md" };
+/** Every marker-merged wrapper a repository gets: the harness's own, then the AGENTS.md pointer. */
+export function briefingWrappers(harness) {
+    return [HARNESS_WRAPPER_TEMPLATE[harness], AGENTS_POINTER];
+}
+/**
+ * Marker pair the wrapper templates use to delimit the method-managed
+ * region. The wrapper sync path slices this region out of the freshly
+ * rendered template and hands it to `writeMarkedBlockFile`.
+ */
+export const WRAPPER_BLOCK_BEGIN = "<!-- method-managed: begin -->";
+export const WRAPPER_BLOCK_END = "<!-- method-managed: end -->";
+/**
+ * Substitute the four canonical variables into a template string. Any
+ * `{{var}}` placeholder whose name is not in the variable set is left
+ * verbatim — callers may pre-check for leftovers if strict rendering
+ * is desired.
+ */
+export function substitute(template, vars) {
+    const map = {
+        sdd_name: vars.sdd_name,
+        repo_kind: vars.repo_kind,
+        baseline_version: vars.baseline_version,
+        sync_date: vars.sync_date,
+    };
+    return template.replace(/\{\{\s*([a-z_][a-z0-9_]*)\s*\}\}/g, (full, key) => {
+        return key in map ? map[key] : full;
+    });
+}
+/**
+ * Find any unresolved `{{var}}` placeholders. Returns the set of
+ * placeholder names (de-duplicated). Callers use this to decide
+ * whether to warn or hard-fail on a stale template.
+ */
+export function findUnresolvedPlaceholders(rendered) {
+    const found = new Set();
+    for (const m of rendered.matchAll(/\{\{\s*([a-z_][a-z0-9_]*)\s*\}\}/g)) {
+        found.add(m[1]);
+    }
+    return [...found];
+}
+export async function renderAgentInstructions(targetRepo, vars) {
+    const templatePath = join(targetRepo, BRIEFING_TEMPLATE_ROOT, "agent-instructions.md.hbs");
+    return renderFromPath(templatePath, vars);
+}
+export async function renderHarnessWrapper(targetRepo, harness, vars) {
+    return renderWrapper(targetRepo, HARNESS_WRAPPER_TEMPLATE[harness].templateRel, vars);
+}
+/** Render one wrapper template from the briefing root; null when the baseline does not ship it. */
+export async function renderWrapper(targetRepo, templateRel, vars) {
+    return renderFromPath(join(targetRepo, BRIEFING_TEMPLATE_ROOT, templateRel), vars);
+}
+/**
+ * Split a fully-rendered wrapper template at the method-managed
+ * markers. The sync flow merges `block` into the existing wrapper and
+ * uses `pre`/`post` as scaffold-fill for blank regions around it.
+ *
+ * Throws when the markers aren't both found — that's a template-
+ * authoring bug, not an adopter-side issue.
+ */
+export function splitWrapperTemplate(rendered) {
+    const beginIdx = rendered.indexOf(WRAPPER_BLOCK_BEGIN);
+    const endIdx = rendered.indexOf(WRAPPER_BLOCK_END, beginIdx);
+    if (beginIdx === -1 || endIdx === -1) {
+        throw new Error("Wrapper template missing method-managed markers: " +
+            `expected ${WRAPPER_BLOCK_BEGIN} ... ${WRAPPER_BLOCK_END} (template-authoring bug)`);
+    }
+    const blockEnd = endIdx + WRAPPER_BLOCK_END.length;
+    return {
+        pre: rendered.slice(0, beginIdx),
+        block: rendered.slice(beginIdx, blockEnd),
+        post: rendered.slice(blockEnd),
+    };
+}
+/**
+ * Extract the method-managed slice (begin marker through end marker,
+ * inclusive) from a fully-rendered wrapper template.
+ */
+export function extractWrapperBlock(rendered) {
+    return splitWrapperTemplate(rendered).block;
+}
+async function renderFromPath(templatePath, vars) {
+    if (!(await fileExists(templatePath)))
+        return null;
+    const raw = await readFile(templatePath, "utf8");
+    const content = substitute(raw, vars);
+    return { content, unresolved: findUnresolvedPlaceholders(content) };
+}
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=render.js.map

package/dist/lib/briefing/variables.js

@@ -0,0 +1,92 @@
+/**
+ * Variable resolution for the briefing layer per ADR 0148 §4.1 + the
+ * Phase 4 setup notes in `adopt-agent-instructions-briefing-layer.md`.
+ *
+ * The four variables are sourced from target-repo state:
+ *
+ *   sdd_name         basename(targetRepo) — overridden by
+ *                    `.sdd/sdd-manifest.yaml::sdd_id` when present.
+ *   repo_kind        `.sdd-repo-kind` content (platform-product /
+ *                    application-product / integration-product /
+ *                    reverse-corpus).
+ *   baseline_version forward-base bundle's `bundle_version` from
+ *                    `method-baseline.lock`.
+ *   sync_date        caller-supplied ISO date (today for init/sync).
+ *
+ * No new YAML parser added — the manifest is a single optional scalar
+ * read; existing scalar-line parser in src/lib/bundle.ts is the
+ * precedent for this style.
+ */
+import { access, readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { readLockFile } from "../lock-file.js";
+import { readRepoKind } from "../repo-kind.js";
+export async function resolveBriefingVariables(opts) {
+    const sdd_name = await resolveSddName(opts.targetRepo);
+    const repo_kind = opts.repoKindOverride ?? (await requireRepoKind(opts.targetRepo));
+    const baseline_version = opts.baselineVersionOverride ??
+        (await resolveBaselineVersion(opts.targetRepo));
+    const sync_date = opts.syncDate ?? todayIso();
+    return { sdd_name, repo_kind, baseline_version, sync_date };
+}
+async function resolveSddName(targetRepo) {
+    const fromManifest = await tryReadSddManifestId(targetRepo);
+    if (fromManifest !== null)
+        return fromManifest;
+    return basename(targetRepo);
+}
+async function tryReadSddManifestId(targetRepo) {
+    const path = join(targetRepo, ".sdd", "sdd-manifest.yaml");
+    if (!(await fileExists(path)))
+        return null;
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+    // Single-scalar line parse, matching bundle.ts style. The catalogue
+    // surface uses a full YAML loader elsewhere; here we only want one
+    // optional field, so this stays dependency-light.
+    for (const line of raw.split("\n")) {
+        const m = /^sdd_id: (.+)$/.exec(line.trim());
+        if (m) {
+            const value = m[1].trim().replace(/^["']|["']$/g, "");
+            if (value.length > 0)
+                return value;
+        }
+    }
+    return null;
+}
+async function requireRepoKind(targetRepo) {
+    const kind = await readRepoKind(targetRepo);
+    if (!kind) {
+        throw new Error(`Cannot resolve briefing variables: .sdd-repo-kind missing at ${targetRepo}`);
+    }
+    return kind;
+}
+async function resolveBaselineVersion(targetRepo) {
+    const lock = await readLockFile(targetRepo);
+    if (!lock) {
+        throw new Error(`Cannot resolve baseline_version: method-baseline.lock missing at ${targetRepo}`);
+    }
+    const forwardBase = lock.bundles.find((b) => b.isForwardBase);
+    if (!forwardBase) {
+        throw new Error(`Cannot resolve baseline_version: no forward-base bundle in method-baseline.lock at ${targetRepo}`);
+    }
+    return forwardBase.bundleVersion;
+}
+function todayIso() {
+    return new Date().toISOString().slice(0, 10);
+}
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=variables.js.map