etymd 0.1.0 → 0.2.1

package/dist/{gates-KPDEUC36.js → gates-3NPKF4IZ.js}

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { planWorkflow, applyFiles } from './chunk-FXL4554F.js';
-import { scanProject } from './chunk-TCWKIMCU.js';
-import './chunk-U33XLT5I.js';
-import { section, print, glyph, theme, renderPlan, git } from './chunk-WVYKYPKS.js';
+import { planWorkflow, applyFiles } from './chunk-4UZBCCFJ.js';
+import { scanProject } from './chunk-E2Q7WFPN.js';
+import './chunk-C4Z6NXDO.js';
+import { section, print, glyph, theme, renderPlan, git } from './chunk-LBRNZZZF.js';
 import { confirm, isCancel, cancel } from '@clack/prompts';
 
 async function run(opts) {

package/dist/index.d.ts

@@ -26,9 +26,42 @@ interface DetectedArtifact {
     label: string;
     path: string;
     /** What role it plays: the single source of truth, a per-agent pointer, a skill, a gate, etc. */
-    kind: "contract" | "state" | "adapter" | "skill" | "gate" | "map" | "sessions" | "other";
+    kind: "contract" | "state" | "decisions" | "adapter" | "skill" | "gate" | "map" | "sessions" | "other";
     exists: boolean;
 }
+/** Committer-date freshness for one state/decisions artifact — a git fact, never mtime. */
+interface ArtifactFreshness {
+    /** Matches `DetectedArtifact.id`. */
+    artifactId: string;
+    path: string;
+    /** ISO committer date (`git log -1 --format=%cI`) of the artifact's last commit. */
+    lastCommit: string;
+    /** True when the repo has commits newer than the artifact's last commit. */
+    commitsSince: boolean;
+    /**
+     * True when the working tree carries uncommitted changes to this artifact — the refresh is
+     * on disk, not yet committed. Treated fresh-now and disclosed, never flagged stale.
+     */
+    dirty?: boolean;
+}
+/**
+ * Freshness of the "this describes now" artifacts (state/decisions), judged from git alone.
+ * mtime is never read — checkouts, syncs, and editors rewrite it freely; the committer date is
+ * the only clock the repo itself vouches for.
+ */
+interface FreshnessFacts {
+    /** ISO committer date of the repo's last commit. */
+    repoLastCommit?: string;
+    artifacts: ArtifactFreshness[];
+    /**
+     * Artifacts whose dates git cannot vouch for (untracked file, shallow clone, not a repo) —
+     * the fact is absent and the lens discloses why; absence is never itself a finding.
+     */
+    unverifiable: {
+        path: string;
+        reason: string;
+    }[];
+}
 interface GitFacts {
     isRepo: boolean;
     branch?: string;
@@ -72,6 +105,8 @@ interface ProjectFacts {
     };
     hooks: HookFacts;
     artifacts: DetectedArtifact[];
+    /** Optional: baselines approved by older versions predate this fact. */
+    freshness?: FreshnessFacts;
     tree: {
         dirs: {
             name: string;
@@ -97,12 +132,19 @@ interface ContextBudget {
     extractionCandidates: ContextFile[];
 }
 
+interface ScanOptions {
+    /**
+     * Fleet: measure repo freshness on fork-authored commits only (`HEAD --not --remotes=<name>`).
+     * The caller verifies the remote exists and discloses the fallback when it does not.
+     */
+    upstreamRemote?: string;
+}
 /**
  * The deterministic half of a reckoning: everything knowable without an LLM. Kept pure of any
  * terminal output so it can back both the CLI and programmatic use, and so it is trivially
  * testable against a fixture directory.
  */
-declare function scanProject(root: string): Promise<ProjectFacts>;
+declare function scanProject(root: string, opts?: ScanOptions): Promise<ProjectFacts>;
 
 /**
  * Default word count above which a single always-loaded file is worth extracting into an
@@ -159,9 +201,16 @@ interface ContextBudgets {
     /** Total always-loaded words past which the footprint itself is a finding. */
     totalWords: number;
 }
+interface StateBudgets {
+    /** Days of commit traffic a state doc may trail the repo by before it counts as stale. */
+    staleAfterDays: number;
+    /** Chars in a state doc past which the file is a finding (session hooks truncate ~10k). */
+    maxChars: number;
+}
 interface EtymdConfig {
     instructions: InstructionScope;
     context: ContextBudgets;
+    state: StateBudgets;
 }
 interface LoadedConfig {
     config: EtymdConfig;
@@ -317,6 +366,20 @@ interface AuditOptions {
     lensIds?: string[];
     /** Persist the reconciled ledger (the default; false = read-only report). */
     persistLedger?: boolean;
+    /**
+     * Fleet: the audited root is READ-ONLY — write nothing into it, not even the scan cache
+     * where `.etymd` already exists there. A corp worktree is never written, regardless of flags.
+     */
+    readOnlyRoot?: boolean;
+    /**
+     * Fleet: read/write the ledger at this root instead of the audited one. Corp findings persist
+     * under the manifest's `corp/<name>/`, never inside the corp worktree.
+     */
+    ledgerRoot?: string;
+    /** Fleet: per-entry state-budget overlay (registry `staleAfterDays` / `stateBudget`). */
+    stateBudgets?: Partial<StateBudgets>;
+    /** Fleet: judge repo freshness on fork-authored commits only (see `ScanOptions`). */
+    upstreamRemote?: string;
 }
 interface AuditResult {
     facts: ProjectFacts;
@@ -331,6 +394,149 @@ interface AuditResult {
 }
 declare function runAudit(root: string, opts?: AuditOptions): Promise<AuditResult>;
 
+type FleetProfile = "personal" | "corp";
+interface FleetContract {
+    state?: string;
+    decisions?: string;
+    goals?: string;
+    /** `"none"` = the contract file is legitimately absent (a declared state, not a gap). */
+    placement?: string;
+}
+interface FleetEntry {
+    name: string;
+    kind?: string;
+    profile: FleetProfile;
+    private: boolean;
+    /** Root-relative path as DECLARED in the tracked manifest (personal entries only). */
+    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;
+    staleAfterDays?: number;
+    /** Per-entry state char-budget override (ships unset — the schema slot exists). */
+    stateBudget?: number;
+    contract: FleetContract;
+    links: Record<string, string>;
+    /** Absolute directory on THIS machine, when the manifest pair resolves one. */
+    resolvedRoot?: string;
+    /** Why `resolvedRoot` is absent — always disclosed, never a silent skip. */
+    unresolved?: string;
+}
+interface ManifestProblem {
+    kind: "parse-error" | "bad-shape" | "local-missing";
+    /** The file the problem lives in (manifest-relative basename). */
+    file: string;
+    detail: string;
+}
+interface FleetManifest {
+    shape: "registry" | "corpus";
+    /** Absolute path of the tracked manifest file. */
+    manifestPath: string;
+    /** Its directory — corp persistence roots and the sweep delta file live beside it. */
+    dir: string;
+    /** Resolved absolute fleet root (registry shape), when declared. */
+    root?: string;
+    machineProfile?: FleetProfile;
+    corpHosts: string[];
+    labels: Record<string, string>;
+    localDirs: Record<string, string>;
+    /** Absolute path where the gitignored local sibling is expected. */
+    localPath: string;
+    localPresent: boolean;
+    entries: FleetEntry[];
+    /** Structural problems — disclosed by every consumer, never defaulted away. */
+    problems: ManifestProblem[];
+}
+/** `~`-expansion is the CONSUMER's job — the tracked manifest never records a machine home. */
+declare function expandTilde(p: string): string;
+/**
+ * Load and resolve a fleet manifest (either shape) against this machine. Never throws on
+ * content problems — they land in `problems` / per-entry `unresolved` so every consumer can
+ * disclose them. Throws only when the manifest file itself cannot be read at all.
+ */
+declare function loadFleetManifest(manifestPath: string): Promise<FleetManifest>;
+
+declare const FLEET_LENS = "fleet-manifest";
+/** The fleet `--json` schema marker — EXPERIMENTAL through 0.2.x, declared in the output. */
+declare const FLEET_JSON_SCHEMA = "fleet-experimental-0.2";
+interface FleetSweepOptions {
+    /** Restrict to these registered names (unknown names throw — a typo must not skip silently). */
+    only?: string[];
+    profile?: "personal" | "corp";
+    /** Truth lenses only per repo (the doctor subset). */
+    kind?: LensKind;
+    /**
+     * Persist per-repo ledgers — ONLY for personal-profile entries that already carry `.etymd`.
+     * The sweep never creates `.etymd` anywhere, and corp worktrees are never written at all.
+     */
+    persistLedgers?: boolean;
+}
+interface FleetProjectSweep {
+    name: string;
+    profile: "personal" | "corp";
+    kind?: string;
+    resolvedRoot?: string;
+    /** Why this entry could not be audited — mirrored into `outOfScope`. */
+    unresolved?: string;
+    staleAfterDays: number;
+    /** Days the newest state artifact trails the repo clock; null = nothing datable. */
+    stateAgeDays: number | null;
+    counts: Record<FindingTier, number>;
+    /** Ranked, ledger-quieted findings from this repo's audit. */
+    findings: Finding[];
+    disclosures: string[];
+}
+interface FleetSweepResult {
+    schema: typeof FLEET_JSON_SCHEMA;
+    manifest: string;
+    sweptAt: string;
+    projects: FleetProjectSweep[];
+    /** Fleet-scope wall findings (`fleet-manifest`) — not ledger-quietable in 0.2. */
+    wall: Finding[];
+    wallDisclosures: string[];
+    /** Entry names that could not be audited — named here, never silently dropped. */
+    outOfScope: string[];
+    /** Manifest problems, verbatim — disclosed by every renderer, never defaulted away. */
+    problems: string[];
+    /** Defect classes open in ≥2 projects — the class-fix candidates (see recurringClasses()). */
+    recurringClasses: RecurringClass[];
+}
+interface RecurringClass {
+    /** The `<lens>/<class>` id prefix — minted by the engine's lenses, identical across repos. */
+    classId: string;
+    tier: FindingTier;
+    /** Project names (corp entries by alias) where the class is currently open. */
+    projects: string[];
+}
+/**
+ * Where a corp entry's audit state persists: beside the manifest, never in the worktree.
+ * Belt-and-braces to the loader's safe-name rule: a name that resolves anywhere but directly
+ * under `<dir>/corp/` is refused — the manifest can lie, and a lie must never steer a write.
+ */
+declare function corpPersistenceRoot(manifest: FleetManifest, name: string): string;
+/**
+ * Validate the manifest pair itself: parse problems, dangling mappings (the live ghost-entry
+ * class), duplicate names, privacy leaks, dead links, machine paths. Pure manifest truth —
+ * no lenses run, no repo is audited, nothing is written.
+ */
+declare function checkManifest(manifest: FleetManifest): Promise<{
+    findings: Finding[];
+    disclosures: string[];
+}>;
+/** All fleet-scope wall checks. Each check that cannot run says so — undetermined, not clean. */
+declare function collectWallFindings(manifest: FleetManifest): Promise<{
+    findings: Finding[];
+    disclosures: string[];
+}>;
+/**
+ * The fleet sweep: one read-only audit per resolved entry + the fleet-scope wall checks.
+ * Invariants (each pinned by test): never creates `.etymd` anywhere; never writes into a corp
+ * worktree regardless of flags or a stray `.etymd` there; unresolvable entries land in
+ * `outOfScope` with a disclosure, never a silent skip.
+ */
+declare function sweepFleet(manifest: FleetManifest, opts?: FleetSweepOptions): Promise<FleetSweepResult>;
+
 /**
  * The truth lens: does what the instruction files CLAIM still hold against the actual repo?
  * Commands must exist as scripts, paths must exist on disk, files must agree on the package
@@ -391,6 +597,20 @@ declare const TOTAL_BUDGET_WORDS: number;
  */
 declare const contextEconomyLens: Lens;
 
+/**
+ * The marker that opts a decisions file into per-entry format checks. Forward-only by design:
+ * mandatory-field checks apply to files that declared the format, never retroactively to
+ * pre-existing records — old decisions are history, not defects.
+ */
+declare const DECISIONS_FORMAT_MARKER = "<!-- decisions-format: 1 -->";
+/**
+ * Freshness lens: does the layer that claims "this describes now" still describe now? Staleness
+ * is RELATIVE — a state doc is stale only when the repo moved past it, so a dormant repo's old
+ * state is current by definition and produces zero findings. Every date is a git committer date
+ * (never mtime); everything git cannot vouch for is disclosed, never flagged.
+ */
+declare const stateFreshnessLens: Lens;
+
 type GateTool = "typecheck" | "lint" | "format-check" | "format-write" | "test" | "coverage" | "e2e" | "sonar" | "codecov" | "commitlint" | "size" | "chromatic";
 interface CiJobGate {
     job: string;
@@ -441,4 +661,4 @@ declare const PACK_VERSION = "2";
 declare const VERSION: string;
 declare const NAME: string;
 
-export { type ApplyResult, type AuditOptions, type AuditResult, type Baseline, CONFIG_FILE, type ContextBudget, type ContextBudgets, type ContextFile, DEFAULT_CONFIG, type DetectedArtifact, type DiscoveredCommands, EXTRACTION_THRESHOLD, type EtymdConfig, type Finding, type GateInventory, type GateTool, type GeneratedFile, type HookFacts, type InstructionFileSet, type InstructionScope, LENSES, type Ledger, type LedgerDiff, type LedgerEntry, type Lens, type LensReport, type LoadedConfig, NAME, PACK_VERSION, type PackageManager, type PathClaims, type PlanOptions, type ProjectFacts, TOTAL_BUDGET_WORDS, VERSION, type WorkflowProfile, type WorkspaceKind, applyFiles, baselineCarriesMachinePath, baselinePath, buildGateInventory, cacheFactsPath, configPath, contextEconomyLens, deriveProfile, extractCommandClaims, extractPathClaims, gateIntegrityLens, instructionTruthLens, isAlwaysAppliedCursorRule, listInstructionFiles, measureContext, planWorkflow, rankFindings, readBaseline, readCachedFacts, readConfig, readLedger, reconcileLedger, runAudit, scanProject, withoutMachinePath, writeBaseline, writeCachedFacts, writeLedger };
+export { type ApplyResult, type ArtifactFreshness, type AuditOptions, type AuditResult, type Baseline, CONFIG_FILE, type ContextBudget, type ContextBudgets, type ContextFile, DECISIONS_FORMAT_MARKER, DEFAULT_CONFIG, type DetectedArtifact, type DiscoveredCommands, EXTRACTION_THRESHOLD, type EtymdConfig, FLEET_JSON_SCHEMA, FLEET_LENS, type Finding, type FleetContract, type FleetEntry, type FleetManifest, type FleetProfile, type FleetProjectSweep, type FleetSweepOptions, type FleetSweepResult, type FreshnessFacts, type GateInventory, type GateTool, type GeneratedFile, type HookFacts, type InstructionFileSet, type InstructionScope, LENSES, type Ledger, type LedgerDiff, type LedgerEntry, type Lens, type LensReport, type LoadedConfig, type ManifestProblem, NAME, PACK_VERSION, type PackageManager, type PathClaims, type PlanOptions, type ProjectFacts, type StateBudgets, TOTAL_BUDGET_WORDS, VERSION, type WorkflowProfile, type WorkspaceKind, applyFiles, baselineCarriesMachinePath, baselinePath, buildGateInventory, cacheFactsPath, checkManifest, collectWallFindings, configPath, contextEconomyLens, corpPersistenceRoot, deriveProfile, expandTilde, extractCommandClaims, extractPathClaims, gateIntegrityLens, instructionTruthLens, isAlwaysAppliedCursorRule, listInstructionFiles, loadFleetManifest, measureContext, planWorkflow, rankFindings, readBaseline, readCachedFacts, readConfig, readLedger, reconcileLedger, runAudit, scanProject, stateFreshnessLens, sweepFleet, withoutMachinePath, writeBaseline, writeCachedFacts, writeLedger };