@karmaniverous/stan-core 0.5.1 → 0.6.0

package/README.md

@@ -2,16 +2,17 @@
 
 # @karmaniverous/stan-core (engine)
 
-[![npm version](https://img.shields.io/npm/v/@karmaniverous/stan-core.svg)](https://www.npmjs.com/package/@karmaniverous/stan-core) ![Node Current](https://img.shields.io/node/v/@karmaniverous/stan-core) <!-- TYPEDOC_EXCLUDE --> [![docs](https://img.shields.io/badge/docs-website-blue)](https://docs.karmanivero.us/stan-core) [![changelog](https://img.shields.io/badge/changelog-latest-blue.svg)](https://github.com/karmaniverous/stan-core/tree/main/CHANGELOG.md)<!-- /TYPEDOC_EXCLUDE --> [![license](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](https://github.com/karmaniverous/stan-core/tree/main/LICENSE.md)
+[![npm version](https://img.shields.io/npm/v/@karmaniverous/stan-core.svg)](https://www.npmjs.com/package/@karmaniverous/stan-core) ![Node Current](https://img.shields.io/node/v/@karmaniverous/stan-core) <!-- TYPEDOC_EXCLUDE --> [![docs](https://img.shields.io/badge/docs-website-blue)](https://docs.karmanivero.us/stan-core) [![changelog](https://img.shields.io/badge/changelog-latest-blue.svg)](https://github.com/karmaniverous/stan-core/tree/main/CHANGELOG.md)<!-- /TYPEDOC_EXCLUDE --> [![license](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](https://github.com/karmaniverous/stan-core/tree/main/LICENSE)
 
 This package exposes the STAN engine as a library:
 
 - File selection (gitignore + includes/excludes + reserved workspace rules)
 - Archiving: full archive.tar and diff archive.diff.tar (binary screening)
 - Patch engine: worktree‑first git apply cascade with jsdiff fallback
-- File Ops: safe mv/rm/rmdir/mkdirp block as “pre‑ops”
+- File Ops: safe mv/cp/rm/rmdir/mkdirp block as “pre‑ops”
 - Config loading/validation (top‑level `stan-core` in stan.config.yml|json)
 - Imports staging under <stanPath>/imports/<label>/…
+- Imports safety: patch + File Ops refuse to modify <stanPath>/imports/** when the correct stanPath is provided
 - Response‑format validator (optional)
 
 For the CLI and TTY runner, see @karmaniverous/stan-cli.
@@ -25,13 +26,14 @@ pnpm add @karmaniverous/stan-core
 
 Node: >= 20
 
+This package is ESM-only (no CommonJS `require()` entrypoint).
+
 ## Quick examples
 
 Create a full archive (binary‑safe) and a diff archive:
 
 ```ts
-import { createArchive } from '@karmaniverous/stan-core/stan';
-import { createArchiveDiff } from '@karmaniverous/stan-core/stan/diff';
+import { createArchive, createArchiveDiff } from '@karmaniverous/stan-core';
 
 const cwd = process.cwd();
 const stanPath = '.stan';
@@ -57,7 +59,7 @@ import {
   detectAndCleanPatch,
   executeFileOps,
   parseFileOpsBlock,
-} from '@karmaniverous/stan-core/stan/patch';
+} from '@karmaniverous/stan-core';
 
 const cwd = process.cwd();
 
@@ -111,7 +113,7 @@ stan-core:
 TypeScript:
 
 ```ts
-import { loadConfig } from '@karmaniverous/stan-core/stan/config';
+import { loadConfig } from '@karmaniverous/stan-core';
 
 const cfg = await loadConfig(process.cwd());
 // cfg has the minimal engine shape:
@@ -124,7 +126,7 @@ const cfg = await loadConfig(process.cwd());
 Stage external imports under <stanPath>/imports/<label>/… before archiving:
 
 ```ts
-import { prepareImports } from '@karmaniverous/stan-core/stan';
+import { prepareImports } from '@karmaniverous/stan-core';
 await prepareImports({
   cwd: process.cwd(),
   stanPath: '.stan',
@@ -137,14 +139,14 @@ await prepareImports({
 Validate assistant responses (optional utility):
 
 ```ts
-import { validateResponseMessage } from '@karmaniverous/stan-core/stan';
+import { validateResponseMessage } from '@karmaniverous/stan-core';
 const res = validateResponseMessage(replyBody);
 if (!res.ok) console.error(res.errors.join('\n'));
 ```
 
 ## API surface
 
-Top‑level (via `import '@karmaniverous/stan-core/stan'`):
+Top‑level (via `import '@karmaniverous/stan-core'`):
 
 - Archiving/diff/snapshot: `createArchive`, `createArchiveDiff`, `writeArchiveSnapshot`
 - Selection/FS: `listFiles`, `filterFiles`
@@ -155,7 +157,7 @@ Top‑level (via `import '@karmaniverous/stan-core/stan'`):
 
 See CHANGELOG for behavior changes. Typedoc site is generated from source.
 
-## Selection precedence and anchors
+## Selection precedence
 
 Core file selection applies in this order:
 
@@ -163,17 +165,19 @@ Core file selection applies in this order:
   - `.git/**`, `<stanPath>/diff/**`, `<stanPath>/patch/**`,
   - archive outputs under `<stanPath>/output/…`,
   - binary screening during archive classification.
-- `includes` override `.gitignore` (but not `excludes`).
-- `excludes` override `includes`.
-- `anchors` (optional) re‑include paths after excludes and `.gitignore`, subject to reserved denials and binary screening.
-
-APIs that accept anchors:
-
-- `filterFiles(files, { …, anchors?: string[] })`
-- `createArchive(cwd, stanPath, { …, anchors?: string[] })`
-- `createArchiveDiff({ …, anchors?: string[] })`
-- `writeArchiveSnapshot({ …, anchors?: string[] })`
-
+- `includes` are additive and can re-include paths ignored by `.gitignore`.
+- `excludes` are hard denials and override `includes`.
+
+## Meta archive (context-mode thread opener)
+
+When dependency graph mode is enabled, the engine can create a small `archive.meta.tar` (via `createMetaArchive`) intended as a thread opener:
+
+- Includes `<stanPath>/system/**` (excluding `<stanPath>/system/.docs.meta.json`)
+- Includes `<stanPath>/context/dependency.meta.json` (required)
+- Includes `<stanPath>/context/dependency.state.json` when present
+- Includes repo-root (top-level) base files selected by current selection config
+- Excludes staged payloads under `<stanPath>/context/{npm,abs}/**` by omission
+
 ## Environment variables
 
 See [Env Vars](./guides/env-vars.md) for a complete list of environment variable switches observed by the engine, tests, and release scripts.
@@ -189,3 +193,7 @@ stan init  # offers to refactor legacy → namespaced; supports --dry-run and ba
 ## License
 
 BSD‑3‑Clause
+
+---
+
+Built for you with ❤️ on Bali! Find more great tools & templates on [my GitHub Profile](https://github.com/karmaniverous).