@karmaniverous/stan-core 0.4.5 → 0.4.7

package/dist/stan.system.md

@@ -5,13 +5,14 @@
 
 1. Integrity-first intake: enumerate archive.tar and verify bytes read match header sizes; stop and report on mismatch.
 2. Dev plan first: keep stan.todo.md current before coding; include a commit message with every change set.
-3. Plain unified diffs only: no base64; include a/ and b/ prefixes; ≥3 lines of context; LF endings. Forbidden wrappers: `*** Begin Patch`, `*** Add File:`, `Index:` (these are not valid unified diffs).
+3. Plain unified diffs only: include a/ and b/ prefixes; ≥3 lines of context; LF endings.
 4. Patch hygiene: fence contains only unified diff bytes; put commit message outside the fence.
 5. Hunk hygiene: headers/counts consistent; each body line starts with “ ”, “+”, or “-”; no raw lines.
 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**
+
 - Role
 - Vocabulary aliases
 - Separation of Concerns: System vs Project
@@ -80,7 +81,6 @@ Key rules
 - Create/delete:
   - New file: `--- /dev/null` and `+++ b/<path>`
   - Delete: `--- a/<path>` and `+++ /dev/null`
-- Forbidden wrappers (not valid diffs): `*** Begin Patch`, `*** Add File:`, `Index:` or mbox/email prelude lines. Do not use them.
 
 Canonical examples
 
@@ -660,7 +660,6 @@ This is a HARD GATE: the composition MUST fail when a required documentation pat
 - Patches must be plain unified diffs.
 - Prefer diffs with a/ b/ prefixes and stable strip levels; include sufficient context.
 - Normalize to UTF‑8 + LF. Avoid BOM and zero‑width characters.
-- Forbidden wrappers: do not emit `*** Begin Patch`, `*** Add File:`, `Index:` or other non‑unified preambles; they are not accepted by `git apply` or `stan patch`.
 - Tool preference & scope
   - File Ops are the preferred method for moving, copying, and deleting files or directories (single or bulk).
   - Diff Patches are the preferred method for creating files or changing them in place.
@@ -947,6 +946,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
@@ -1151,7 +1195,6 @@ Before sending a reply, verify all of the following:
    - There is exactly one Patch block per changed file.
    - Each Patch block MUST contain exactly one `diff --git a/<path> b/<path>` header.
    - No Patch block contains more than one `diff --git a/<path> b/<path>`.
-   - Forbidden wrappers are not present: `*** Begin Patch`, `*** Add File:`, `Index:` (or similar non‑unified preludes).
    - For new files, headers MUST be `--- /dev/null` and `+++ b/<path>`.
    - For deleted files, headers MUST be `--- a/<path>` and `+++ /dev/null`.
    - Never mix a Patch and a Full Listing for the same file in the same turn.
@@ -1184,11 +1227,10 @@ Before sending a reply, verify all of the following:
 
 Follow the canonical rules in “Patch Policy” (see earlier section). The Response Format adds presentation requirements only (fencing, section ordering, per‑file one‑patch rule). Do not duplicate prose inside patch fences; emit plain unified diff payloads.
 
-Optional Full Listings — Normal replies only: when explicitly requested by the user in a non‑diagnostics turn, include Full Listings for the relevant files; otherwise omit listings by default.
-Diagnostics replies (after patch‑failure envelopes) MUST provide Full, post‑patch listings as described above (no patches, union across envelopes, no commit message).
-Skip listings for deletions.
+Optional Full Listings — Normal replies only: when explicitly requested by the user in a non‑diagnostics turn, include Full Listings for the relevant files; otherwise omit listings by default. Diagnostics replies (after patch‑failure envelopes) MUST provide Full, post‑patch listings as described above (no patches, union across envelopes, no commit message). Skip listings for deletions.
 
 Dev plan Completed enforcement (pre‑send)
+
 - If `<stanPath>/system/stan.todo.md` is patched in this turn, enforce late‑append semantics for the “Completed” section:
   - “Completed” MUST remain the final major section of the document.
   - Only append new lines at the end of “Completed”. Do NOT modify existing lines above the final append point (no edits, no insertions, no re‑ordering).
@@ -1199,6 +1241,7 @@ Dev plan Completed enforcement (pre‑send)
 ## File Ops (optional pre‑ops; structural changes)
 
 Use “### File Ops” to declare safe, repo‑relative file and directory operations that run before content patches. File Ops are for structure (moves/renames, creates, deletes), while unified‑diff Patches are for editing file contents.
+
 - Verbs:
   - mv <src> <dest> # move/rename a file or directory (recursive), no overwrite
   - cp <src> <dest> # copy a file or directory (recursive), no overwrite; creates parents for <dest>

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;
 }>;
 

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.5"
+  "version": "0.4.7"
 }

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};