@karmaniverous/stan-core 0.3.0 → 0.4.1

package/dist/stan.system.md

@@ -801,6 +801,55 @@ diff --git a/new/path/to/file/a.ts b/new/path/to/file/a.ts
 - When attaching artifacts for chat, prefer attaching `<stanPath>/output/archive.tar` (and `<stanPath>/output/archive.diff.tar` when present). If `--combine` was not used, you may also attach the text outputs individually.
 - Important: Inside any attached archive, contextual files are located in the directory matching the `stanPath` key from `stan.config.*` (default `.stan`). The bootloader resolves this automatically.
 
+# Facet‑aware editing guard (think beyond the next turn)
+
+Purpose
+- Prevent proposing content patches for files that are absent from the attached archives because a facet is inactive this run (overlay enabled).
+- Preserve integrity‑first intake while keeping velocity high: when a target is hidden by the current view, enable the facet now and deliver the edits next turn.
+
+Inputs to read first (when present)
+- `<stanPath>/system/.docs.meta.json` — overlay record for this run:
+  - `overlay.enabled: boolean`
+  - `overlay.effective: Record<facet, boolean>` (true = active)
+- `<stanPath>/system/facet.meta.json` — durable facet definitions:
+  - `name → { exclude: string[]; include: string[] }`
+  - exclude lists define facetized subtrees; include lists are anchors (always kept)
+
+Guardrail (hard rule)
+- If `overlay.enabled === true` and a target path falls under any facet whose `overlay.effective[facet] === false` (inactive this run), do NOT emit a content Patch for that target in this turn.
+- Instead:
+  - Explain that the path is hidden by an inactive facet this run.
+  - Enable the facet for the next run:
+    - Prefer a patch to `<stanPath>/system/facet.state.json` setting that facet to `true` (next‑run default), and
+    - Tell the user to re‑run with `stan run -f <facet>` (overlay ON; facet active) or `stan run -F` (overlay OFF) for a full baseline.
+  - Log the intent in `<stanPath>/system/stan.todo.md` (“enable facet <name> to edit <path> next turn”).
+  - Deliver the actual content edits in the next turn after a run with the facet active (or overlay disabled).
+
+Allowed mixing (keep velocity without violating integrity)
+- It is OK to:
+  - Patch other files that are already visible in this run.
+  - Update `facet.meta.json` (e.g., add anchors) together with `facet.state.json`.
+  - Create or update anchor documents (breadcrumbs) even when the facet is currently inactive — anchors are always included in the next run once listed in `include`.
+- It is NOT OK to:
+  - Emit a content Patch for a file under a facet you are enabling in the same turn.
+  - Attempt to override reserved denials (`.git/**`, `<stanPath>/diff/**`, `<stanPath>/patch/**`, and archive outputs under `<stanPath>/output/…`); anchors never override these.
+
+Resolution algorithm (assistant‑side; POSIX paths)
+1) Load `.docs.meta.json`. If absent or `overlay.enabled !== true`, skip this guard.
+2) Load `facet.meta.json` and derive subtree roots for each facet’s `exclude` patterns (strip common glob tails like `/**` or `/*`, trim trailing “/”; ignore leaf‑globs such as `**/*.test.ts` for subtree matching).
+3) For each intended patch target:
+   - If the target lies under any facet subtree and that facet is inactive per `overlay.effective`, block the edit this turn and propose facet activation instead (see Guardrail).
+4) If overlay metadata is missing but the target file is simply absent from the archive set, treat this as a hidden target; ask to re‑run with `-f <facet>` or `-F` and resume next turn.
+
+Optional metadata (CLI nicety; not required)
+- When `overlay.facetRoots: Record<facet, string[]>` is present in `.docs.meta.json`, prefer those pre‑normalized subtree roots over local glob heuristics.
+
+Notes
+- Reserved denials and binary screening always win; anchors cannot re‑include them.
+- The goal is two‑turn cadence for hidden targets:
+  - Turn N: enable the facet + log intent.
+  - Turn N+1: deliver the content edits once the target is present in archives.
+
 # Default Task (when files are provided with no extra prompt)
 
 Primary objective — Plan-first

package/dist/types/index.d.ts

@@ -16,8 +16,38 @@ type CreateArchiveOptions = {
     excludes?: string[];
     /** Optional callback for archive classifier warnings (engine remains silent by default). */
     onArchiveWarnings?: (text: string) => void;
+    /**
+     * High‑precedence re‑includes (subject to reserved denials and output exclusion).
+     * Anchors re-include paths even when excluded by `.gitignore` or `excludes`,
+     * but they never override reserved workspace denials:
+     * - `<stanPath>/diff/**`, `<stanPath>/patch/**`
+     * - `<stanPath>/output/{archive.tar,archive.diff.tar,archive.warnings.txt}`
+     * - `.git/**`
+     *
+     * @example
+     * ```ts
+     * // Force-include README.md even if repo excludes would drop it:
+     * await createArchive(cwd, '.stan', {
+     *   includes: [],
+     *   excludes: ['README.md'],
+     *   anchors: ['README.md'],
+     * });
+     * ```
+     */
+    anchors?: string[];
 };
-/** Create `stanPath/output/archive.tar` (or custom file name) from the repo root. */
+/**
+ * Create `stanPath/output/archive.tar` (or custom file name) from the repo root.
+ *
+ * @example
+ * ```ts
+ * const tarPath = await createArchive(process.cwd(), '.stan', {
+ *   includeOutputDir: false,
+ *   excludes: ['**\/.tsbuild/**'],
+ *   anchors: ['README.md', 'docs/index.md'], // re-include anchors
+ * });
+ * ```
+ */
 declare const createArchive: (cwd: string, stanPath: string, options?: CreateArchiveOptions) => Promise<string>;
 
 /** Public default STAN path for consumers and internal use. */
@@ -93,13 +123,26 @@ type SnapshotUpdateMode = 'never' | 'createIfMissing' | 'replace';
  *   - stanPath: STAN workspace folder.
  *   - includes: Allow‑list globs (overrides excludes).
  *   - excludes: Deny‑list globs.
+ *   - anchors: High‑precedence re‑includes (subject to reserved/output).
+ *
+ * @example
+ * ```ts
+ * // Seed snapshot using anchors to keep README.md even when excluded:
+ * await writeArchiveSnapshot({
+ *   cwd: process.cwd(),
+ *   stanPath: '.stan',
+ *   excludes: ['README.md'],
+ *   anchors: ['README.md'],
+ * });
+ * ```
  * @returns Absolute path to the `.archive.snapshot.json` file.
  */
-declare const writeArchiveSnapshot: ({ cwd, stanPath, includes, excludes, }: {
+declare const writeArchiveSnapshot: ({ cwd, stanPath, includes, excludes, anchors, }: {
     cwd: string;
     stanPath: string;
     includes?: string[];
     excludes?: string[];
+    anchors?: string[];
 }) => Promise<string>;
 /**
  * Create a diff tar at <stanPath>/output/<baseName>.diff.tar.
@@ -116,11 +159,25 @@ declare const writeArchiveSnapshot: ({ cwd, stanPath, includes, excludes, }: {
  *   - baseName: Base archive name (e.g., `archive` -\> `archive.diff.tar`).
  *   - includes: Allow‑list globs (overrides excludes).
  *   - excludes: Deny‑list globs.
+ *   - anchors: High‑precedence re‑includes (subject to reserved/output).
  *   - updateSnapshot: Controls when the snapshot file is replaced.
  *   - includeOutputDirInDiff: When true, include `stanPath/output` in the diff.
  * @returns `{ diffPath }` absolute path to the diff archive.
+ *
+ * @example
+ * ```ts
+ * // Diff archive with anchors to retain docs/overview.md:
+ * const { diffPath } = await createArchiveDiff({
+ *   cwd: process.cwd(),
+ *   stanPath: '.stan',
+ *   baseName: 'archive',
+ *   excludes: ['docs/**'],
+ *   anchors: ['docs/overview.md'],
+ *   updateSnapshot: 'createIfMissing',
+ * });
+ * ```
  */
-declare const createArchiveDiff: ({ cwd, stanPath, baseName, includes, excludes, updateSnapshot, includeOutputDirInDiff, onArchiveWarnings, }: {
+declare const createArchiveDiff: ({ cwd, stanPath, baseName, includes, excludes, updateSnapshot, includeOutputDirInDiff, anchors, onArchiveWarnings, }: {
     cwd: string;
     stanPath: string;
     baseName: string;
@@ -128,6 +185,7 @@ declare const createArchiveDiff: ({ cwd, stanPath, baseName, includes, excludes,
     excludes?: string[];
     updateSnapshot?: SnapshotUpdateMode;
     includeOutputDirInDiff?: boolean;
+    anchors?: string[];
     onArchiveWarnings?: (text: string) => void;
 }) => Promise<{
     diffPath: string;
@@ -279,6 +337,14 @@ declare const prepareImports: (args: {
     onStage?: (label: string, files: string[]) => void;
 }) => Promise<void>;
 
+/**
+ * Compile an engine‑parity matcher that returns true when any pattern matches.
+ *
+ * @param patterns - Glob/prefix patterns (POSIX paths).
+ * @returns (relPath) =\> boolean
+ */
+declare const makeGlobMatcher: (patterns: string[]) => ((rel: string) => boolean);
+
 /** Resolve packaged dist/stan.system.md if present. */
 declare const getPackagedSystemPromptPath: () => string | null;
 
@@ -304,5 +370,5 @@ declare const assembleSystemMonolith: (cwd: string, stanPath: string) => Promise
 
 declare const CORE_VERSION: string;
 
-export { CORE_VERSION, DEFAULT_OPEN_COMMAND, DEFAULT_STAN_PATH, __internal, applyPatchPipeline, applyWithJsDiff, assembleSystemMonolith, createArchive, createArchiveDiff, detectAndCleanPatch, ensureOutputDir, executeFileOps, findConfigPathSync, getPackagedSystemPromptPath, loadConfig, loadConfigSync, parseFileOpsBlock, prepareImports, resolveStanPath, resolveStanPathSync, validateOrThrow, validateResponseMessage, writeArchiveSnapshot };
+export { CORE_VERSION, DEFAULT_OPEN_COMMAND, DEFAULT_STAN_PATH, __internal, applyPatchPipeline, applyWithJsDiff, assembleSystemMonolith, createArchive, createArchiveDiff, detectAndCleanPatch, ensureOutputDir, executeFileOps, findConfigPathSync, getPackagedSystemPromptPath, loadConfig, loadConfigSync, makeGlobMatcher, parseFileOpsBlock, prepareImports, resolveStanPath, resolveStanPathSync, validateOrThrow, validateResponseMessage, writeArchiveSnapshot };
 export type { ApplyResult, AssembleResult, AttemptCapture, Block, BlockKind, ContextConfig, CreateArchiveOptions, FileOp, FileOpsPlan, ImportsMap, JsDiffOutcome, OpResult, PipelineOutcome, SnapshotUpdateMode, ValidationResult };

package/package.json

@@ -12,14 +12,14 @@
   "dependencies": {
     "@vitest/eslint-plugin": "^1.3.15",
     "diff": "^8.0.2",
-    "fs-extra": "^11.3.2",
     "fast-glob": "^3.3.3",
+    "fs-extra": "^11.3.2",
     "glob-parent": "^6.0.2",
     "ignore": "^7.0.5",
     "package-directory": "^8.1.0",
     "picomatch": "^4.0.3",
-    "zod": "^4.1.11",
-    "yaml": "^2.8.1"
+    "yaml": "^2.8.1",
+    "zod": "^4.1.11"
   },
   "description": "Engine for STAN — programmatic archiving/diffing/snapshotting, patch application, config loading, selection, and imports staging. No CLI/TTY concerns.",
   "devDependencies": {
@@ -151,5 +151,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.3.0"
+  "version": "0.4.1"
 }