etymd 0.2.2 → 0.3.1

package/dist/gates-WIGDS5VF.js

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+import { applyFiles } from './chunk-EF6BPBG6.js';
+import { derivedCommands, planWorkflow, runPrefix, isSafeGateCommand } from './chunk-VFUYQLW7.js';
+import { readConfig, CONFIG_FILE, configPath } from './chunk-NMZ3RHWW.js';
+import { section, print, glyph, theme, renderPlan } from './chunk-TADKOW6P.js';
+import { scanProject } from './chunk-HOLFW5QY.js';
+import './chunk-DKC7MLWG.js';
+import './chunk-R74SJ7HS.js';
+import './chunk-CRJHIXJH.js';
+import { readText, git } from './chunk-YLNQQZ5F.js';
+import { promises } from 'node:fs';
+import path from 'node:path';
+import { confirm, isCancel, cancel, select, multiselect } from '@clack/prompts';
+
+function detectIndent(raw) {
+  const m = raw.match(/\n(\s+)"/);
+  if (!m) return 2;
+  const ws = m[1];
+  return ws.includes("	") ? "	" : ws.length;
+}
+function mergeScriptInto(raw, key, value) {
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch (err) {
+    return {
+      result: {
+        outcome: "unparsable",
+        detail: err instanceof Error ? err.message : String(err)
+      }
+    };
+  }
+  const scripts = doc.scripts ?? {};
+  const current = scripts[key];
+  if (typeof current === "string") {
+    if (current === value) return { result: { outcome: "unchanged" } };
+    return { result: { outcome: "conflict", existing: current } };
+  }
+  const indent = detectIndent(raw);
+  const next = { ...doc, scripts: { ...scripts, [key]: value } };
+  const trailing = raw.endsWith("\n") ? "\n" : "";
+  return { text: JSON.stringify(next, null, indent) + trailing, result: { outcome: "added" } };
+}
+async function ensurePackageScript(pkgPath, key, value) {
+  const raw = await readText(pkgPath);
+  if (raw === null) return { outcome: "absent" };
+  const { text, result } = mergeScriptInto(raw, key, value);
+  if (text) await promises.writeFile(pkgPath, text, "utf8");
+  return result;
+}
+
+// src/commands/gates.ts
+var PUBLISH_GATE_SCRIPT = "scripts/artifact-check.sh";
+var PUBLISH_GATE_VALUE = `./${PUBLISH_GATE_SCRIPT}`;
+function publishGateKey(route) {
+  return route === "vscode" ? "vscode:prepublish" : "prepublishOnly";
+}
+function printGateSummary(gates, facts, source) {
+  const run2 = runPrefix(facts.packageManager);
+  const cmds = gates.commands.length ? gates.commands.map((c) => `${run2} ${c}`).join(", ") : "none detected";
+  print(`  ${glyph.bullet} ${theme.dim("pre-push runs")} ${theme.info(cmds)}`);
+  print(`  ${glyph.bullet} ${theme.dim("audit fails on")} ${theme.info(gates.failOn)}`);
+  print(
+    `  ${glyph.bullet} ${theme.dim("publish screen")} ${theme.info(gates.publishGate ? "yes" : "no")}${gates.publishGate && !facts.publishable ? theme.dim(" (overridden)") : ""}`
+  );
+  if (source.recorded || source.willRecord) {
+    print(`  ${theme.dim(`change any of these later in ${CONFIG_FILE}`)}`);
+  } else {
+    print(
+      `  ${theme.dim(`derived from this repo \u2014 write ${CONFIG_FILE} (or run without --yes) to pin them`)}`
+    );
+  }
+}
+async function customize(current, facts) {
+  const c = facts.commands;
+  const available = [c.formatCheck, c.typecheck, c.lint, c.test].filter(
+    (k) => Boolean(k)
+  );
+  const picked = available.length ? await multiselect({
+    message: "Which commands should the pre-push gate run?",
+    required: false,
+    initialValues: current.commands,
+    options: available.map((k) => ({
+      value: k,
+      label: `${runPrefix(facts.packageManager)} ${k}`,
+      hint: isSafeGateCommand(c.raw[k]) ? void 0 : "writes \u2014 allowed only if you pick it"
+    }))
+  }) : [];
+  if (isCancel(picked)) return void 0;
+  const tier = await select({
+    message: "Fail the push on which finding tier?",
+    initialValue: current.failOn,
+    options: [
+      { value: "risk", label: "risk \u2014 only what makes an agent do the wrong thing" },
+      { value: "gap", label: "gap \u2014 also dead references and missing safeguards" },
+      { value: "polish", label: "polish \u2014 everything" }
+    ]
+  });
+  if (isCancel(tier)) return void 0;
+  const publish = await confirm({
+    message: "Screen the published artifact? (the only check that sees what actually ships)",
+    initialValue: current.publishGate ?? facts.publishable
+  });
+  if (isCancel(publish)) return void 0;
+  const commands = picked;
+  return {
+    commands,
+    failOn: tier,
+    publishGate: publish,
+    // Picking a writing command IS the override — recorded so the generator honors it.
+    allowWriting: commands.filter((k) => !isSafeGateCommand(c.raw[k]))
+  };
+}
+function mergeGateSection(previous, gates) {
+  const merged = { ...previous, ...gates };
+  const why = previous._why;
+  if (!why) return merged;
+  const next = gates;
+  const kept = Object.fromEntries(
+    Object.entries(why).filter(
+      ([field]) => JSON.stringify(previous[field]) === JSON.stringify(next[field])
+    )
+  );
+  if (Object.keys(kept).length) merged._why = kept;
+  else delete merged._why;
+  return merged;
+}
+async function writeGateConfig(root, gates) {
+  const target = configPath(root);
+  const existing = await readText(target);
+  let doc = {};
+  if (existing) {
+    try {
+      doc = JSON.parse(existing);
+    } catch {
+      return;
+    }
+  }
+  doc.gates = mergeGateSection(doc.gates ?? {}, gates);
+  await promises.mkdir(path.dirname(target), { recursive: true });
+  await promises.writeFile(target, JSON.stringify(doc, null, 2) + "\n", "utf8");
+}
+async function run(opts) {
+  const facts = await scanProject(opts.cwd);
+  if (opts.ci) {
+    section("CI review gate");
+    print(
+      `  ${glyph.partial} ${theme.dim("The advisory AI-review CI job (bring-your-own-key) ships in a later release \u2014 installing the free local gates below.")}`
+    );
+  }
+  if (!facts.git.isRepo) {
+    print(
+      `  ${glyph.bad} ${theme.dim("Not a git repository \u2014 local hooks need git. Run `git init` first.")}`
+    );
+    return;
+  }
+  if (facts.hooks.source === "husky" || facts.hooks.source === "husky-legacy" || facts.hooks.source === "custom") {
+    print(
+      `  ${glyph.partial} ${theme.warn(`${facts.hooks.source} already manages hooks here.`)} ${theme.dim("git runs ONE hook path \u2014 installing .githooks + core.hooksPath takes over. Fold the existing hook logic in first.")}`
+    );
+    if (!opts.yes) {
+      const go = await confirm({ message: "Proceed with .githooks anyway?", initialValue: false });
+      if (isCancel(go) || !go) {
+        cancel("No changes made.");
+        return;
+      }
+    }
+  }
+  const existingPrePush = await readText(path.join(opts.cwd, ".githooks", "pre-push"));
+  const { config, present: hasConfig } = await readConfig(opts.cwd);
+  const configSource = { recorded: hasConfig, willRecord: !opts.yes };
+  let gateConfig = {
+    ...config.gates,
+    commands: config.gates.commands.length ? config.gates.commands : derivedCommands(facts, existingPrePush ?? void 0),
+    publishGate: config.gates.publishGate ?? facts.publishable
+  };
+  const plan = async () => {
+    const files = await planWorkflow(opts.cwd, facts, {
+      agents: false,
+      gates: true,
+      gateConfig
+    });
+    return files.filter((f) => f.executable);
+  };
+  let gateFiles = await plan();
+  renderPlan(gateFiles);
+  printGateSummary(gateConfig, facts, configSource);
+  if (!opts.yes) {
+    const choice = await select({
+      message: "Install these gates?",
+      initialValue: "yes",
+      options: [
+        { value: "yes", label: "yes \u2014 install as shown" },
+        { value: "customize", label: "customize \u2014 change what the gates run" },
+        { value: "no", label: "cancel" }
+      ]
+    });
+    if (isCancel(choice) || choice === "no") {
+      cancel("No changes made.");
+      return;
+    }
+    if (choice === "customize") {
+      const customized = await customize(gateConfig, facts);
+      if (!customized) {
+        cancel("No changes made.");
+        return;
+      }
+      gateConfig = customized;
+      gateFiles = await plan();
+      renderPlan(gateFiles);
+      printGateSummary(gateConfig, facts, configSource);
+    }
+    await writeGateConfig(opts.cwd, gateConfig);
+  }
+  const overwrite = /* @__PURE__ */ new Set();
+  for (const f of gateFiles) {
+    if (!f.exists) continue;
+    if (!f.differs) {
+      overwrite.add(f.path);
+      continue;
+    }
+    if (opts.yes) continue;
+    const ow = await confirm({
+      message: `${f.path} exists with different content (hand-edited?). Overwrite with the pack version?`,
+      initialValue: false
+    });
+    if (isCancel(ow)) {
+      cancel("No changes made.");
+      return;
+    }
+    if (ow) overwrite.add(f.path);
+  }
+  const result = await applyFiles(opts.cwd, gateFiles, overwrite);
+  await git(opts.cwd, ["config", "core.hooksPath", ".githooks"]);
+  section("Done");
+  for (const w of result.written) print(`  ${glyph.ok} ${theme.dim("wrote")} ${theme.info(w)}`);
+  for (const sk of result.skipped)
+    print(`  ${glyph.bullet} ${theme.dim("kept (hand-edited)")} ${theme.dim(sk)}`);
+  print(`  ${glyph.ok} ${theme.dim("set")} ${theme.code("core.hooksPath = .githooks")}`);
+  const wrotePublishGate = result.written.includes(PUBLISH_GATE_SCRIPT);
+  if (wrotePublishGate) {
+    const pkgPath = path.join(opts.cwd, "package.json");
+    const PUBLISH_GATE_KEY = publishGateKey(facts.publishRoute);
+    {
+      const merged = await ensurePackageScript(pkgPath, PUBLISH_GATE_KEY, PUBLISH_GATE_VALUE);
+      if (merged.outcome === "added")
+        print(`  ${glyph.ok} ${theme.dim("wired")} ${theme.code(PUBLISH_GATE_KEY)}`);
+      else if (merged.outcome === "conflict")
+        print(
+          `  ${glyph.partial} ${theme.warn(`${PUBLISH_GATE_KEY} already runs \`${merged.existing}\``)} ${theme.dim("\u2014 left as is; chain the screen into it by hand if you want both.")}`
+        );
+      else if (merged.outcome === "unchanged")
+        print(`  ${glyph.bullet} ${theme.dim(`${PUBLISH_GATE_KEY} already wired`)}`);
+      else
+        print(
+          `  ${glyph.partial} ${theme.dim(`package.json ${merged.outcome}${merged.detail ? `: ${merged.detail}` : ""} \u2014 wire ${PUBLISH_GATE_KEY} by hand`)}`
+        );
+    }
+  }
+}
+
+export { mergeGateSection, run };

package/dist/generate-I75IEXXF.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+export { derivedCommands, planWorkflow } from './chunk-VFUYQLW7.js';
+import './chunk-NMZ3RHWW.js';
+import './chunk-R74SJ7HS.js';
+import './chunk-CRJHIXJH.js';
+import './chunk-YLNQQZ5F.js';

package/dist/index.d.ts

@@ -70,7 +70,7 @@ interface GitFacts {
     husky: boolean;
     /** Distinct commit authors in recent history — the solo-vs-team profile signal. */
     recentAuthors?: number;
-    /** Ticket-key prefix inferred from recent commit subjects (e.g. "NGRE2E"). */
+    /** Ticket-key prefix inferred from recent commit subjects (e.g. "PROJ"). */
     ticketKey?: string;
 }
 interface HookFacts {
@@ -104,6 +104,22 @@ interface ProjectFacts {
         files: string[];
     };
     hooks: HookFacts;
+    /**
+     * This project would publish something if asked — a manifest exists and does not declare
+     * `private: true`.
+     *
+     * A GUESS, not a fact: npm treats a missing `private` as publishable, which is right about
+     * npm's semantics and wrong about a local fork nobody will ever publish. It seeds the plan;
+     * `gates.publishGate` in `.etymd/config.json` overrides it for good.
+     */
+    publishable: boolean;
+    /**
+     * How this project publishes, when it does. The route decides which manifest key fires a
+     * publish-time gate: npm runs `prepublishOnly`, while `vsce` ignores that key entirely and
+     * runs `vscode:prepublish` — so wiring the npm key into an extension is a gate that silently
+     * never runs.
+     */
+    publishRoute: "npm" | "vscode" | "none";
     artifacts: DetectedArtifact[];
     /** Optional: baselines approved by older versions predate this fact. */
     freshness?: FreshnessFacts;
@@ -159,35 +175,6 @@ declare const EXTRACTION_THRESHOLD: number;
 declare function isAlwaysAppliedCursorRule(text: string): boolean;
 declare function measureContext(root: string, perFileWords?: number): Promise<ContextBudget>;
 
-interface GeneratedFile {
-    path: string;
-    contents: string;
-    /** Present on disk already — apply will skip or ask before overwriting. */
-    exists: boolean;
-    /** The existing file's content differs from what the pack would generate (hand-edited or stale). */
-    differs?: boolean;
-    /** Hooks need the executable bit. */
-    executable?: boolean;
-    label: string;
-}
-interface PlanOptions {
-    /** Scaffold a minimal AGENTS.md (init only offers this when none exists). */
-    agents: boolean;
-    gates: boolean;
-}
-/** Build the file set an onboarding would write, flagging which exist and which differ. */
-declare function planWorkflow(root: string, facts: ProjectFacts, opts: PlanOptions): Promise<GeneratedFile[]>;
-
-interface ApplyResult {
-    written: string[];
-    skipped: string[];
-}
-/**
- * Write a planned file set. Idempotent by default: an existing file is skipped unless `overwrite`
- * names it — etymd never clobbers hand-authored contracts without consent.
- */
-declare function applyFiles(root: string, files: GeneratedFile[], overwrite?: Set<string>): Promise<ApplyResult>;
-
 declare const CONFIG_FILE: string;
 interface InstructionScope {
     /** Extra instruction files to audit beyond the auto-detected set (globs, repo-relative). */
@@ -207,10 +194,29 @@ interface StateBudgets {
     /** Chars in a state doc past which the file is a finding (session hooks truncate ~10k). */
     maxChars: number;
 }
+/**
+ * What the generated gates should contain. Every field here is DERIVED from the repo on a first
+ * run and written into the plan, not asked: a wrong guess costs a slightly slow hook or a
+ * slightly strict audit, and both are one edit away. Prompting is reserved for the choices where
+ * a wrong default is expensive — trust (a permanent leak) and the publish gate (a write into
+ * package.json). Recording the derivation here is what makes `gates` re-runnable without
+ * re-deciding, and what a drift check compares against.
+ */
+interface GateConfig {
+    /** Command keys the pre-push gate runs, in order. Empty = whatever the scan finds. */
+    commands: string[];
+    /** Tier the audit step fails on: risk | gap | polish. */
+    failOn: string;
+    /** Emit the publish-time screen. Unset = derive from whether the repo publishes. */
+    publishGate?: boolean;
+    /** Commands allowed into a gate despite looking like they write (an explicit override). */
+    allowWriting: string[];
+}
 interface EtymdConfig {
     instructions: InstructionScope;
     context: ContextBudgets;
     state: StateBudgets;
+    gates: GateConfig;
 }
 interface LoadedConfig {
     config: EtymdConfig;
@@ -228,6 +234,43 @@ declare function configPath(root: string): string;
  */
 declare function readConfig(root: string): Promise<LoadedConfig>;
 
+interface GeneratedFile {
+    path: string;
+    contents: string;
+    /** Present on disk already — apply will skip or ask before overwriting. */
+    exists: boolean;
+    /** The existing file's content differs from what the pack would generate (hand-edited or stale). */
+    differs?: boolean;
+    /** Hooks need the executable bit. */
+    executable?: boolean;
+    label: string;
+}
+interface PlanOptions {
+    /** Scaffold a minimal AGENTS.md (init only offers this when none exists). */
+    agents: boolean;
+    gates: boolean;
+    /**
+     * Emit the publish-time screen. Defaults to `facts.publishable` — set it explicitly to
+     * override the derivation (a repo that publishes by a route npm cannot see, or one that
+     * declines the door).
+     */
+    publishGate?: boolean;
+    /** Recorded gate choices; absent means derive everything from the scan. */
+    gateConfig?: GateConfig;
+}
+/** Build the file set an onboarding would write, flagging which exist and which differ. */
+declare function planWorkflow(root: string, facts: ProjectFacts, opts: PlanOptions): Promise<GeneratedFile[]>;
+
+interface ApplyResult {
+    written: string[];
+    skipped: string[];
+}
+/**
+ * Write a planned file set. Idempotent by default: an existing file is skipped unless `overwrite`
+ * names it — etymd never clobbers hand-authored contracts without consent.
+ */
+declare function applyFiles(root: string, files: GeneratedFile[], overwrite?: Set<string>): Promise<ApplyResult>;
+
 type FindingTier = "risk" | "gap" | "polish";
 type Effort = "S" | "M" | "L";
 type Confidence = "high" | "medium" | "low";
@@ -395,6 +438,35 @@ interface AuditResult {
 declare function runAudit(root: string, opts?: AuditOptions): Promise<AuditResult>;
 
 type FleetProfile = "personal" | "corp";
+/**
+ * How exposed an entry's history is, or could plausibly become. A SAFETY PREDICATE, not a label:
+ * it decides whether content screening applies, so absence must never read as the permissive
+ * answer. `checkManifest` treats an undeclared non-corp entry as a finding — a repo published
+ * without ever answering the question is exactly the case a default would hide.
+ *
+ *   `public-repo`   already public — outside-contribution surface.
+ *   `public-bound`  private today, plausibly public later. Screened as hard as public, because
+ *                   publishing exposes ALL history: the scrub must precede the first commit,
+ *                   not the visibility flip.
+ *   `private`       not destined to be published. An ANSWER, not the absence of one.
+ *
+ * Corp entries do not carry it — `profile: "corp"` implies the answer (machine-pinned, never
+ * publishable), so requiring it there would be ceremony.
+ */
+type FleetTrust = "public-repo" | "public-bound" | "private";
+/**
+ * Fleet-wide orientation: the one entry every other entry is guided by.
+ *
+ * Declared ONCE at the manifest level rather than as a per-entry link, because the relationship
+ * is constant — a per-entry field carries no information and can be forgotten, which is exactly
+ * how three entries came to be silently unlinked. Hoisting it makes the orphan state
+ * unrepresentable instead of merely detectable. A fleet with no orientation root simply omits
+ * the block; etymd never assumes one exists.
+ */
+interface FleetOrientation {
+    /** Registered name of the orientation root. Only the root itself is exempt from being guided. */
+    root: string;
+}
 interface FleetContract {
     state?: string;
     decisions?: string;
@@ -411,9 +483,24 @@ interface FleetEntry {
     path?: string;
     /** Remote name of the upstream this repo forks — freshness measures fork-authored commits. */
     upstream?: string;
-    /** `"public-repo"` marks an outside-contribution surface (hygiene needles apply). */
-    trust?: string;
+    /**
+     * How exposed this entry is — see {@link FleetTrust}. `"public-repo"` marks an
+     * outside-contribution surface (hygiene needles apply). Undeclared on a non-corp entry is a
+     * `fleet check` finding, never a silent "private".
+     */
+    trust?: FleetTrust;
+    /** A declared `trust` value outside the vocabulary — preserved verbatim so the check can name it. */
+    trustRaw?: string;
     staleAfterDays?: number;
+    /**
+     * How this entry's git hooks are governed. `"none"` declares that generated gates are
+     * deliberately absent — a prose repo with nothing mechanically checkable, or one whose gate is
+     * hand-written on purpose. Wall findings cannot be quieted through the ledger (004: their only
+     * honest resolution is fixing them), which is right for leak and partition conditions but
+     * wrong for a state a fleet legitimately chooses; without this, a settled decision is
+     * re-reported on every sweep until the report is ignored.
+     */
+    gates?: string;
     /** Per-entry state char-budget override (ships unset — the schema slot exists). */
     stateBudget?: number;
     contract: FleetContract;
@@ -437,6 +524,8 @@ interface FleetManifest {
     dir: string;
     /** Resolved absolute fleet root (registry shape), when declared. */
     root?: string;
+    /** Fleet-wide orientation root, when the manifest declares one. Absent = this fleet has none. */
+    orientation?: FleetOrientation;
     machineProfile?: FleetProfile;
     corpHosts: string[];
     labels: Record<string, string>;
@@ -656,7 +745,7 @@ declare const gateIntegrityLens: Lens;
  * change meaning. Stamped into facts, baselines, and generated artifacts so drift against the
  * pack is computable and `harvest` has something to diff.
  */
-declare const PACK_VERSION = "2";
+declare const PACK_VERSION = "3";
 
 declare const VERSION: string;
 declare const NAME: string;