@karmaniverous/stan-core 0.4.6 → 0.4.7

package/dist/stan.system.md

@@ -946,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

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.6"
+  "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};