etymd 0.2.2 → 0.3.0

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,8 +483,14 @@ 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;
     /** Per-entry state char-budget override (ships unset — the schema slot exists). */
     stateBudget?: number;
@@ -437,6 +515,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 +736,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;