@karmaniverous/stan-core 0.4.6 → 0.5.0

package/dist/stan.system.md

@@ -11,7 +11,9 @@
 6. Coverage: one Patch per changed file. Full Listings are not required by default in normal replies; include them only on explicit request. Diagnostics replies require Full Listings only (no patches). Skip listings for deletions.
 7. Services‑first: ports & adapters; thin adapters; pure services; co‑located tests.
 8. Long‑file rule: ~300 LOC threshold; propose splits or justify exceptions; record plan/justification in stan.todo.md.
-9. Fence hygiene: choose fence length dynamically (max inner backticks + 1); re‑scan after composing. **Table of Contents**
+9. Fence hygiene: wrap code blocks in tilde fences (default `~~~~`), bump to `~`×(N+1) when content contains `~`×N; re‑scan after composing.
+
+**Table of Contents**
 
 - Role
 - Vocabulary aliases
@@ -280,22 +282,26 @@ When the unexpected happens, a short design iteration almost always produces a b
 # Dependency Bug Report
 
 Purpose
+
 - When a dependency fails, offer a concise, valid‑Markdown bug report that upstream (human or STAN) can consume.
 - Keep the report self‑contained (short excerpts inline). Prefer links for large evidence; defer artifacts to a later iteration.
 
 Fence hygiene
-- When presenting this template in chat, wrap the entire template body in a fence chosen by the Fence Hygiene (Quick How‑To) algorithm and re‑scan before sending. Do not rely on a fixed backtick count.
+
+- When presenting this template in chat, wrap the entire template body in a fence chosen by the Fence Hygiene (Quick How‑To) algorithm and re‑scan before sending. Do not rely on a fixed tilde count.
 
 Canonical template (copy/paste the body; wrap per fence‑hygiene rules)
 
 # Dependency Bug Report — <package>@<version>
 
 ## Summary
+
 - What: <1–2 sentences describing the failure in downstream usage>
 - Where: <downstream repo name> (<relative paths>)
 - Impact: <blocking | partial | annoyance>; Scope: <modules affected>
 
 ## Environment
+
 - Downstream repo: <name> @ <commit or tag>
 - Node: <x.y.z> (<os/arch>)
 - Package manager: <npm|pnpm|yarn> <version>
@@ -303,11 +309,13 @@ Canonical template (copy/paste the body; wrap per fence‑hygiene rules)
 - Tooling: TypeScript <x.y>, Bundler <rollup/vite/webpack>, ESLint/TSConfig notes (if relevant)
 
 ## Reproduction (minimal)
-1) <command or step>
-2) <command or step>
-3) Observe: <expected vs actual>
+
+1. <command or step>
+2. <command or step>
+3. Observe: <expected vs actual>
 
 Example:
+
 ```bash
 pnpm i
 pnpm run build
@@ -316,12 +324,15 @@ pnpm run build
 ```
 
 ## Evidence (concise)
+
 Primary error excerpt:
+
 ```text
 <copy the minimal error lines + 2–5 lines of context>
 ```
 
 If a minimal code change triggers it, show the tiniest diff:
+
 ```diff
 diff --git a/src/example.ts b/src/example.ts
 --- a/src/example.ts
@@ -332,29 +343,35 @@ diff --git a/src/example.ts b/src/example.ts
 ```
 
 ## Root cause hypothesis (best‑effort)
+
 - <e.g., subpath export missing; ESM/CJS mismatch; types not published; side effects; changed API signature>
 - Why we think so: <brief rationale, links to docs/source lines>
 
 ## Proposed fix (what we need from upstream)
-1) <concrete change, e.g., “add subpath export ./mutator in package.json”>
-2) <build/output change, e.g., “publish .d.ts alongside JS outputs”>
-3) <docs note or migration guidance, if applicable>
+
+1. <concrete change, e.g., “add subpath export ./mutator in package.json”>
+2. <build/output change, e.g., “publish .d.ts alongside JS outputs”>
+3. <docs note or migration guidance, if applicable>
 
 ## Acceptance criteria
+
 - After publishing:
   - <import/build/test> succeeds without local hacks.
   - TypeScript resolves types without path alias overrides.
   - No <specific error codes/warnings> remain in a fresh install.
 
 ## Attachments or links (evidence)
+
 - Preferred: links to logs, a minimal repro repo, or a PR that demonstrates the issue clearly.
 - Avoid bundling artifacts in the same message as this report to prevent ingestion confusion by tools that auto‑process archives.
 
 ## Notes for downstream (we’ll handle)
+
 - <local pin/guard we will apply temporarily; removed after fix>
 - <config/doc updates we’ll make once published>
 
 ## Maintainer contact
+
 - Upstream repo: <url>
 - Issue link (if already filed): <url or “to be filed”>
 
@@ -946,6 +963,51 @@ Notes
   - Reserved denials remain in effect (e.g., do not place content under `/<stanPath>/diff/**`, `/<stanPath>/patch/**`, or archive outputs in `/<stanPath>/output/**`).
   - The facet‑aware editing guard still applies: do not propose edits under an inactive facet this run; enable the facet first and emit patches next turn.
 
+# STAN assistant guide — creation & upkeep policy
+
+This repository SHOULD include a “STAN assistant guide” document at
+`guides/stan-assistant-guide.md`, unless the project prompt explicitly declares
+a different single, stable path for the guide (in which case, that declared path
+is authoritative).
+
+The assistant guide exists to let STAN assistants use and integrate the library
+effectively without consulting external type definition files or other project
+documentation.
+
+Policy
+
+- Creation (required):
+  - If the assistant guide is missing, create it as part of the first change set
+    where you would otherwise rely on it (e.g., when adding/altering public APIs,
+    adapters, configuration, or key workflows).
+  - Prefer creating it in the same turn as the first relevant code changes so it
+    cannot drift from reality.
+- Maintenance (required):
+  - Treat the guide as a maintained artifact, not a one-off doc.
+  - Whenever a change set materially affects how an assistant should use the
+    library (public exports, configuration shape/semantics, runtime invariants,
+    query contracts, paging tokens, projection behavior, adapter
+    responsibilities, or common pitfalls), update the guide in the same change
+    set.
+  - When deprecating/renaming APIs or changing semantics, update the guide and
+    include migration guidance (old → new), but keep it concise.
+- Intent (what the guide must enable):
+  - Provide a self-contained description of the “mental model” (runtime behavior
+    and invariants) and the minimum working patterns (how to configure, how to
+    call core entrypoints, how to integrate a provider/adapter).
+  - Include only the information required to use the library correctly; omit
+    narrative or historical context.
+- Constraints (how to keep it effective and reusable):
+  - Keep it compact: “as short as possible, but as long as necessary.”
+  - Make it self-contained: do not require readers to import or open `.d.ts`
+    files, TypeDoc pages, or other repo docs to understand core contracts.
+  - Avoid duplicating durable requirements or the dev plan:
+    - Requirements belong in `stan.requirements.md`.
+    - Work tracking belongs in `stan.todo.md`.
+    - The assistant guide should focus on usage contracts and integration.
+  - Define any acronyms locally on first use within the guide (especially if
+    used outside generic type parameters).
+
 # Default Task (when files are provided with no extra prompt)
 
 Primary objective — Plan-first
@@ -1012,7 +1074,7 @@ If info is insufficient to proceed without critical assumptions, abort and clari
 ## Commit message output
 
 - MANDATORY: Commit message MUST be wrapped in a fenced code block.
-  - Use a plain triple-backtick fence (or longer per the fence hygiene rule if needed).
+  - Use a tilde fence (default `~~~~`, or longer per the fence hygiene rule if needed).
   - Do not annotate with a language tag; the block must contain only the commit message text.
   - Emit the commit message once, at the end of the reply.
   - This rule applies to every change set, regardless of size.
@@ -1024,7 +1086,7 @@ If info is insufficient to proceed without critical assumptions, abort and clari
     - “When: <UTC timestamp>”
     - “Why: <short reason>”
     - “What changed:” bulleted file list with terse notes
-- The fenced commit message MUST be placed in a code block fence that satisfies the +1 backtick rule (see Response Format).
+- The fenced commit message MUST be placed in a code block fence that satisfies the tilde fence hygiene rule (see Response Format).
 - When patches are impractical, provide Full Listings for changed files, followed by the commit message. Do not emit unified diffs in that mode.
 
 Exception — patch failure diagnostics:
@@ -1036,29 +1098,47 @@ Exception — patch failure diagnostics:
 
 # Fence Hygiene (Quick How‑To)
 
-Goal: prevent hashed or broken templates/examples that contain nested code blocks.
+Goal: prevent broken Markdown when emitting fenced blocks, especially diffs and
+Markdown listings that contain embedded backtick fences.
 
-Algorithm
-1) Scan every block you will emit (patches, templates, examples). Compute the maximum contiguous run of backticks inside each block’s content.
-2) Choose the outer fence length as N = (max inner backticks) + 1 (minimum 3).
-3) Re‑scan after composing. If any block’s outer fence is ≤ the max inner run, bump N and re‑emit.
+Default wrapper
+
+- Use **tilde fences** for all fenced code blocks we emit (Patch blocks, Full
+  Listings, templates/examples, and Commit Message blocks).
+- Start with a **default fence of `~~~~`** (4 tildes). Tilde fences are valid
+  Markdown but rare in code/docs, so collisions are much less common than with
+  backtick fences.
+
+Algorithm (tilde-based)
+
+1) Scan every block you will emit. Compute the maximum contiguous run of `~`
+   characters that appears anywhere in that block’s content.
+2) Choose the outer fence length as `N = max(4, maxInnerTildes + 1)`.
+3) Emit the block wrapped in `~`×N.
+4) Re‑scan after composing. If any block’s outer fence is `<= maxInnerTildes`,
+   bump N and re‑emit.
 
 Hard rule (applies everywhere)
-- Do not rely on a fixed backtick count. Always compute, then re‑scan.
-- This applies to the Dependency Bug Report template, patch failure diagnostics envelopes, and any example that includes nested fenced blocks.
+- Do not rely on a fixed tilde count. Always compute, then re‑scan.
+- This applies to Patch blocks, Full Listings, the Dependency Bug Report
+  template, patch-failure diagnostics envelopes, and any example that includes
+  fenced blocks.
 
 # Response Format (MANDATORY)
 
 CRITICAL: Fence Hygiene (Nested Code Blocks) and Coverage
 
-- You MUST compute fence lengths dynamically to ensure that each outer fence has one more backtick than any fence it contains.
+- Use **tilde fences** for all fenced blocks emitted in replies (Patch blocks,
+  Full Listings, and Commit Message). Default is `~~~~`.
+- You MUST compute fence lengths dynamically to ensure that each outer fence has
+  one more `~` than any `~` run it contains (minimum 4).
 - Algorithm:
   1. Collect all code blocks you will emit (every “Patch” per file; any optional “Full Listing” blocks, if requested).
-  2. For each block, scan its content and compute the maximum run of consecutive backticks appearing anywhere inside (including literals in examples).
-  3. Choose the fence length for that block as maxInnerBackticks + 1 (minimum 3).
-  4. If a block contains other fenced blocks (e.g., an example that itself shows fences), treat those inner fences as part of the scan. If the inner block uses N backticks, the enclosing block must use at least N+1 backticks.
+  2. For each block, scan its content and compute the maximum run of consecutive `~` characters appearing anywhere inside (including literals in examples).
+  3. Choose the fence length for that block as `max(4, maxInnerTildes + 1)`.
+  4. If a block contains other fenced blocks (e.g., an example that itself shows fences), treat those inner fences as part of the scan. If the inner content uses `~`×N, the enclosing block must use at least `~`×(N+1).
   5. If a file has both a “Patch” and an optional “Full Listing”, use the larger fence length for both blocks.
-  6. Never emit a block whose outer fence length is less than or equal to the maximum backtick run inside it.
+  6. Never emit a block whose outer fence length is less than or equal to the maximum `~` run inside it.
   7. After composing the message, rescan each block and verify the rule holds; if not, increase fence lengths and re‑emit.
 
 General Markdown formatting
@@ -1092,10 +1172,10 @@ Use these headings exactly; wrap each Patch (and optional Full Listing, when app
 
 <change summary>
 
-```
+~~~~
 ### File Ops
 <one operation per line>
-```
+~~~~
 
 ## Input Data Changes
 
@@ -1127,17 +1207,17 @@ Use these headings exactly; wrap each Patch (and optional Full Listing, when app
 
 ## Commit Message
 
-- Output the commit message at the end of the reply wrapped in a fenced code block. Do not annotate with a language tag. Apply the +1 backtick rule. The block contains only the commit message (subject + body), no surrounding prose.
+- Output the commit message at the end of the reply wrapped in a fenced code block. Do not annotate with a language tag. Apply the tilde fence-hygiene rule. The block contains only the commit message (subject + body), no surrounding prose.
 
 ## Validation
 
 - Normal replies:
   - Confirm one Patch block per changed file (and zero Full Listings).
-  - Confirm fence lengths obey the +1 backtick rule for every block.
+  - Confirm fence lengths obey the tilde fence hygiene rule for every block.
   - Confirm that no Patch would cause any file to exceed 300 LOC; pivoted decomposition patches instead.
 - Diagnostics replies (after patch‑failure envelopes):
   - Confirm that the reply contains Full Listings only (no patches), one per affected file (union across envelopes).
-  - Confirm fence lengths obey the +1 backtick rule for every block.
+  - Confirm fence lengths obey the tilde fence hygiene rule for every block.
   - Confirm that no listed file exceeds 300 LOC; if it would, pivoted decomposition + listings for the decomposed files instead.
 
 ---
@@ -1160,7 +1240,7 @@ Before sending a reply, verify all of the following:
    - Diagnostics replies (after patch‑failure envelopes): Do NOT emit a Commit Message.
 
 3. Fence hygiene (+1 rule)
-   - For every fenced block, the outer fence is strictly longer than any internal backtick run (minimum 3).
+   - For every fenced block, the outer fence is strictly longer than any internal `~` run (minimum 4).
    - Patches, optional Full Listings, and commit message all satisfy the +1 rule.
 4. Section headings
    - Headings match the template exactly (names and order).
@@ -1169,7 +1249,7 @@ Before sending a reply, verify all of the following:
    - Normal replies: If any Patch block is present, there MUST also be a Patch for <stanPath>/system/stan.todo.md that reflects the change set (unless the change set is deletions‑only or explicitly plan‑only). The “Commit Message” MUST be present and last.
    - Diagnostics replies: Skip Commit Message; listings‑only for the affected files.
 6. Nested-code templates (hard gate)
-   - Any template or example that contains nested fenced code blocks (e.g., the Dependency Bug Report or a patch failure diagnostics envelope) MUST pass the fence‑hygiene scan: compute N = maxInnerBackticks + 1 (min 3), apply that fence, then re‑scan before sending. If any collision remains, STOP and re‑emit. If any check fails, STOP and re‑emit after fixing. Do not send a reply that fails these checks.
+   - Any template or example that contains nested fenced code blocks (e.g., the Dependency Bug Report or a patch failure diagnostics envelope) MUST pass the fence‑hygiene scan: compute N = max(4, maxInnerTildes + 1), apply that tilde fence, then re‑scan before sending. If any collision remains, STOP and re‑emit. If any check fails, STOP and re‑emit after fixing. Do not send a reply that fails these checks.
 7. Dev plan “Completed” (append‑only; last)
    - If `.stan/system/stan.todo.md` is patched:
      - “Completed” is still the final major section of the document.

package/dist/types/index.d.ts

@@ -48,7 +48,7 @@ type CreateArchiveOptions = {
  * });
  * ```
  */
-declare const createArchive: (cwd: string, stanPath: string, options?: CreateArchiveOptions) => Promise<string>;
+declare function createArchive(cwd: string, stanPath: string, options?: CreateArchiveOptions): Promise<string>;
 
 /** Public default STAN path for consumers and internal use. */
 declare const DEFAULT_STAN_PATH = ".stan";
@@ -137,13 +137,13 @@ type SnapshotUpdateMode = 'never' | 'createIfMissing' | 'replace';
  * ```
  * @returns Absolute path to the `.archive.snapshot.json` file.
  */
-declare const writeArchiveSnapshot: ({ cwd, stanPath, includes, excludes, anchors, }: {
+declare function writeArchiveSnapshot({ cwd, stanPath, includes, excludes, anchors, }: {
     cwd: string;
     stanPath: string;
     includes?: string[];
     excludes?: string[];
     anchors?: string[];
-}) => Promise<string>;
+}): Promise<string>;
 /**
  * Create a diff tar at <stanPath>/output/<baseName>.diff.tar.
  * - If snapshot exists: include only changed files.
@@ -177,7 +177,7 @@ declare const writeArchiveSnapshot: ({ cwd, stanPath, includes, excludes, anchor
  * });
  * ```
  */
-declare const createArchiveDiff: ({ cwd, stanPath, baseName, includes, excludes, updateSnapshot, includeOutputDirInDiff, anchors, onArchiveWarnings, }: {
+declare function createArchiveDiff({ cwd, stanPath, baseName, includes, excludes, updateSnapshot, includeOutputDirInDiff, anchors, onArchiveWarnings, }: {
     cwd: string;
     stanPath: string;
     baseName: string;
@@ -187,7 +187,7 @@ declare const createArchiveDiff: ({ cwd, stanPath, baseName, includes, excludes,
     includeOutputDirInDiff?: boolean;
     anchors?: string[];
     onArchiveWarnings?: (text: string) => void;
-}) => Promise<{
+}): Promise<{
     diffPath: string;
 }>;
 
@@ -246,6 +246,10 @@ type FileOp = {
     verb: 'mv';
     src: string;
     dest: string;
+} | {
+    verb: 'cp';
+    src: string;
+    dest: string;
 } | {
     verb: 'rm';
     src: string;

package/package.json

@@ -130,7 +130,7 @@
       ]
     },
     "npm": {
-      "publish": true
+      "publish": false
     }
   },
   "repository": {
@@ -152,5 +152,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.4.6"
+  "version": "0.5.0"
 }

package/dist/cjs/classifier-D1njCQ3L.js

@@ -1 +0,0 @@
-"use strict";var t=require("node:fs/promises"),e=require("node:path");const n=1048576;exports.classifyForArchive=async(r,s)=>{const i=[],a=[],o=[];await Promise.all(s.map(async s=>{const c=s.replace(/\\/g,"/");const l=e.resolve(r,s);let h=0;try{h=(await t.stat(l)).size}catch{return}let u,p=!1;try{p=await(async e=>{try{const n=await t.open(e,"r");try{const t=Buffer.allocUnsafe(8192),{bytesRead:e}=await n.read(t,0,t.length,0);for(let n=0;n<e;n+=1)if(0===t[n])return!0;return!1}finally{await n.close().catch(()=>{})}}catch{return!1}})(l)}catch{p=!1}if(p)return void a.push({path:c,size:h});i.push(c);try{if(h<=n||h<5*n){u=(t=>{const e=t.replace(/\r\n/g,"\n");return 0===e.length?0:e.split("\n").length})(await t.readFile(l,"utf8"))}}catch{}(h>n||"number"==typeof u&&u>3e3)&&o.push({path:c,size:h,loc:u})}));const c=[];if(a.length>0){c.push(`Binary files excluded from archive (${a.length.toString()}):`);for(const t of a)c.push(`  - ${t.path}  (${t.size.toString()} bytes)`);c.push("")}if(o.length>0){c.push(`Large text files (included; consider excludes if unwanted) (${o.length.toString()}):`);for(const t of o){const e=[`  - ${t.path}`,`(${t.size.toString()} bytes)`];"number"==typeof t.loc&&e.push(`${t.loc.toString()} LOC`),c.push(e.join(" "))}c.push(""),c.push(`Thresholds: size > ${n.toString()} bytes or LOC > ${3e3.toString()}`)}0===c.length&&c.push("No archive warnings.");const l=c.join("\n")+(c.length?"\n":"");return{textFiles:i,excludedBinaries:a,largeText:o,warningsBody:l}};

package/dist/mjs/classifier-DeYwffC_.js

@@ -1 +0,0 @@
-import{stat as t,readFile as e,open as n}from"node:fs/promises";import{resolve as r}from"node:path";const s=1048576,o=async(o,i)=>{const a=[],c=[],h=[];await Promise.all(i.map(async i=>{const l=i.replace(/\\/g,"/");const u=r(o,i);let p=0;try{p=(await t(u)).size}catch{return}let f,g=!1;try{g=await(async t=>{try{const e=await n(t,"r");try{const t=Buffer.allocUnsafe(8192),{bytesRead:n}=await e.read(t,0,t.length,0);for(let e=0;e<n;e+=1)if(0===t[e])return!0;return!1}finally{await e.close().catch(()=>{})}}catch{return!1}})(u)}catch{g=!1}if(g)return void c.push({path:l,size:p});a.push(l);try{if(p<=s||p<5*s){f=(t=>{const e=t.replace(/\r\n/g,"\n");return 0===e.length?0:e.split("\n").length})(await e(u,"utf8"))}}catch{}(p>s||"number"==typeof f&&f>3e3)&&h.push({path:l,size:p,loc:f})}));const l=[];if(c.length>0){l.push(`Binary files excluded from archive (${c.length.toString()}):`);for(const t of c)l.push(`  - ${t.path}  (${t.size.toString()} bytes)`);l.push("")}if(h.length>0){l.push(`Large text files (included; consider excludes if unwanted) (${h.length.toString()}):`);for(const t of h){const e=[`  - ${t.path}`,`(${t.size.toString()} bytes)`];"number"==typeof t.loc&&e.push(`${t.loc.toString()} LOC`),l.push(e.join(" "))}l.push(""),l.push(`Thresholds: size > ${s.toString()} bytes or LOC > ${3e3.toString()}`)}0===l.length&&l.push("No archive warnings.");const u=l.join("\n")+(l.length?"\n":"");return{textFiles:a,excludedBinaries:c,largeText:h,warningsBody:u}};export{o as classifyForArchive};