@onedotmint/charterleaf 0.2.1 → 0.4.0

package/lib/project.js

@@ -0,0 +1,142 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { fileURLToPath } = require('node:url');
+const { createHash, randomUUID } = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+
+const MODES = ['auto', 'confirm', 'reference', 'off'];
+const CONFIG = 'specs/.charterleaf.json';
+
+function projectRoot(cwd) {
+  const start = fs.realpathSync(cwd);
+  for (let current = start; ; current = path.dirname(current)) {
+    if (fs.existsSync(path.join(current, '.git')) || fs.existsSync(path.join(current, CONFIG))) return current;
+    if (path.dirname(current) === current) return start;
+  }
+}
+
+function inside(root, file) {
+  const relative = path.relative(root, file);
+  return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+
+// Resolve existing ancestors too: new files below a symlink must not escape the project.
+function canonical(file, depth = 0) {
+  if (depth > 40) throw new Error('Too many symlinks');
+  try {
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink()) return canonical(path.resolve(path.dirname(file), fs.readlinkSync(file)), depth + 1);
+    return fs.realpathSync(file);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    const parent = path.dirname(file);
+    if (parent === file) return file;
+    return path.join(canonical(parent, depth + 1), path.basename(file));
+  }
+}
+
+function toolPath(input) {
+  let value = input.replace(/[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g, ' ');
+  if (value.startsWith('@')) value = value.slice(1);
+  if (value.startsWith('file://')) value = fileURLToPath(value);
+  value = value.replaceAll('\\', '/');
+  if (value === '~') value = os.homedir();
+  if (value.startsWith('~/')) value = path.join(os.homedir(), value.slice(2));
+  if (process.platform === 'win32') {
+    const drive = value.match(/^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/(.*))?$/i);
+    if (drive) value = `${drive[1].toUpperCase()}:/${drive[2] || ''}`;
+  }
+  return value;
+}
+
+function projectPath(root, cwd, input) {
+  if (typeof input !== 'string' || !input || input.includes('\0')) return null;
+  let value = toolPath(input);
+  if (process.platform !== 'win32' && /^[A-Za-z]:\//.test(value)) {
+    value = `/mnt/${value[0].toLowerCase()}/${value.slice(3)}`;
+  } else if (process.platform !== 'win32' && value.startsWith('//')) {
+    // A foreign UNC host cannot safely be interpreted as a local Linux path.
+    return null;
+  }
+  const lexical = path.resolve(cwd, value);
+  const resolved = canonical(lexical);
+  if (!inside(root, lexical) || !inside(root, resolved)) return null;
+  return path.relative(root, resolved).replaceAll('\\', '/') || '.';
+}
+
+function readMode(root) {
+  const file = path.join(root, CONFIG);
+  if (!fs.existsSync(file)) return 'off';
+  if (!inside(root, canonical(file))) throw new Error('Charterleaf config escapes project');
+  const config = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (config.version !== 1 || !MODES.includes(config.mode)) throw new Error('Invalid Charterleaf config (expected version: 1 and a valid mode)');
+  return config.mode;
+}
+
+function saveMode(root, mode) {
+  if (!MODES.includes(mode)) throw new Error('Invalid Charterleaf mode');
+  const file = path.join(root, CONFIG);
+  if (!inside(root, canonical(file))) throw new Error('Charterleaf config escapes project');
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, `${JSON.stringify({ version: 1, mode }, null, 2)}\n`, { flag: 'wx' });
+    fs.renameSync(temporary, file);
+  } finally {
+    if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
+  }
+}
+
+function fingerprint(root, relative) {
+  const file = path.join(root, relative);
+  if (!inside(root, canonical(file))) return 'outside';
+  try {
+    const stat = fs.statSync(file);
+    if (!stat.isFile()) return 'not-file';
+    // shortcut: over 2 MiB use size/mtime, use streaming hashes if large-file attribution is needed.
+    if (stat.size > 2 * 1024 * 1024) return `large:${stat.size}:${stat.mtimeMs}`;
+    return createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+  } catch (error) {
+    if (error.code === 'ENOENT') return 'missing';
+    throw error;
+  }
+}
+
+function gitSnapshot(root) {
+  const git = (args) => execFileSync('git', ['-C', root, ...args], {
+    encoding: 'utf8', timeout: 3000, maxBuffer: 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  try {
+    if (fs.realpathSync(git(['rev-parse', '--show-toplevel']).trim()) !== root) return null;
+    // Compare index and worktree separately; this also works before the first commit.
+    const names = [git(['diff', '--no-renames', '--name-only', '-z']), git(['diff', '--cached', '--no-renames', '--name-only', '-z']),
+      git(['ls-files', '--others', '--exclude-standard', '-z'])].join('\0').split('\0').filter(Boolean);
+    if (names.length > 500) return null; // Bounded task checks, not a repository scan.
+    const snapshot = new Map([...new Set(names)].map((name) => {
+      const file = path.join(root, name);
+      // Git tracks a symlink's target string, not the target file's contents.
+      let stat;
+      try { stat = fs.lstatSync(file); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+      const hash = stat?.isSymbolicLink() ? `symlink:${fs.readlinkSync(file)}` : fingerprint(root, name);
+      return [name, hash];
+    }));
+    const raw = git(['diff', '--cached', '--raw', '--no-abbrev', '--no-renames', '-z']).split('\0');
+    snapshot.index = new Map();
+    for (let i = 0; i + 1 < raw.length; i += 2) snapshot.index.set(raw[i + 1], raw[i]);
+    return snapshot;
+  } catch {
+    return null;
+  }
+}
+
+function changedSince(before, after) {
+  if (!before || !after) return [];
+  return [...new Set([...before.keys(), ...after.keys()])].filter((name) =>
+    (before.get(name) ?? 'clean') !== (after.get(name) ?? 'clean') ||
+    before.index?.get(name) !== after.index?.get(name)).sort();
+}
+
+module.exports = { CONFIG, MODES, projectRoot, projectPath, toolPath, readMode, saveMode, fingerprint, gitSnapshot, changedSince };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@onedotmint/charterleaf",
-  "version": "0.2.1",
-  "description": "A tiny specification layer for coding agents.",
+  "version": "0.4.0",
+  "description": "Lightweight Agent-Native Constraint Layer: opt-in spec discovery and maintenance for Pi, with a standalone zero-dependency CLI.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -20,6 +20,7 @@
   "files": [
     "bin/",
     "lib/",
+    "extensions/",
     "skills/",
     "templates/",
     "AGENTS_SNIPPET.md",
@@ -32,12 +33,17 @@
     "coding-agent",
     "specification",
     "agent-skills",
-    "pi"
+    "pi",
+    "pi-package"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "test:pi": "node scripts/pi-smoke.js"
   },
   "pi": {
+    "extensions": [
+      "./extensions/charterleaf.js"
+    ],
     "skills": [
       "./skills"
     ]

package/skills/charterleaf/SKILL.md

@@ -1,58 +1,37 @@
 ---
 name: charterleaf
-description: A tiny specification layer for durable project intent and constraints.
+description: Discover and maintain durable project constraints when Charterleaf is explicitly enabled or requested.
+disable-model-invocation: true
 ---
 
-# Charterleaf
+# Charterleaf authoring guide
 
-Treat Charterleaf as a small knowledge layer, not a workflow system.
+The essential rules live in [runtime.md](runtime.md); read it only if not already supplied. The Pi Extension supplies those rules automatically only when the project is enabled via `/charterleaf`; it does not preload this guide. Outside Pi, use the CLI only when explicitly requested. Existing `specs/` alone does not enable automation; do not initialize documents or recommend adoption automatically.
 
-When a concrete code path is known, run:
+Read this guide only for unfamiliar spec formats, staged changes or manual CLI use. Ordinary code edits need no Skill read or CLI call when applicable constraints have already been supplied.
 
-```bash
-charterleaf related <path>
-```
+## Ownership and durable writing
 
-Read only the returned living specs and active changes.
+Source owns implementation; tests own executable verification; `AGENTS.md` owns project entry/navigation; specs own durable constraints. Never copy signatures, inventories, current state or existing documentation into specs. Link the authoritative owner instead. Charterleaf is not task management, planning, memory, evidence, history or a project workflow.
 
-When the relevant code path is not yet known, run:
+Place only established, non-obvious knowledge whose absence could cause a future mistake:
 
-```bash
-charterleaf map
-```
+- `specs/constitution.md`: rare project-wide boundaries;
+- `specs/capabilities/`: observable contracts, invariants and non-goals;
+- `specs/engineering/`: long-lived implementation boundaries, recurring pitfalls and verification constraints;
+- `specs/decisions/`: accepted rationale and revisit conditions.
 
-Use the map only to discover available specification scopes. Do not read every listed specification by default. Use normal code navigation to locate the smallest relevant area. Once a concrete path is known, run `charterleaf related <path>`.
+Living capability/engineering specs need a unique `id` and non-empty `applies_to` list. Keep scope narrow, preserve existing formats and requirement IDs, and verify explicit local references normally. `anchors` and `verified_by` are not required. Do not create speculative standards or code summaries to satisfy a final review.
 
-For broad project-level questions, start with normal project entry documents. Do not expand into every spec or project-state document merely because no path was provided. `map` is not semantic search.
+## Optional staged changes
 
-Use authority in this order:
+Use `specs/changes/<name>.md` only when an accepted future contract must coexist with current truth: review, another session or an ongoing migration. Supply valid `affects` spec IDs and at least one non-empty `ADD`, `MODIFY` or `REMOVE` section; `PRESERVE` alone is not a change. Once implemented and verified, merge durable truth into living specs and remove obsolete staging. Git keeps history; never commit automatically.
 
-```text
-Constitution > Active Change > Living Spec > Current Code
-```
+## CLI details
 
-Keep specs compressed and evidence-based. Prefer contracts over commentary and durable pitfalls over patterns obvious from code. Never invent aspirational standards; record only demonstrated or explicitly accepted intent.
+Run from the project root:
 
-Do not touch specs for renames, lint cleanup, routine refactors, temporary debugging, Todo/status changes, or trivial fixes with no durable implication.
+- `charterleaf related <path>` returns constitution as Global, capability/engineering specs matching `applies_to`, and active changes affecting returned spec IDs. It returns paths/metadata, not bodies. Decisions and explicit references are followed manually when relevant. A scoped miss is not proof that no constraints apply.
+- `charterleaf lint` checks frontmatter, IDs/globs, duplicate IDs, change references/deltas and conflicting active changes. `0 structural errors` does not prove semantic correctness, coverage or code/spec agreement. The Extension also lints standard spec writes.
 
-After non-trivial implementation or debugging, consider whether durable project knowledge was discovered. If so, record only the durable result:
-
-- observable behavior, contract, invariant, or non-goal → capability spec;
-- long-lived implementation constraint, boundary, recurring pitfall, or required verification practice → engineering spec;
-- important architectural choice, rationale, or revisit condition → decision.
-
-If nothing durable was learned, do not modify specs. Do not record current task status, implementation progress, temporary debugging notes, one-off commands, session history, Todo items, or transient observations. Specs accumulate durable project knowledge, not development activity.
-
-For a durable bug fix, use `Current` and `Expected` when useful and state what must `PRESERVE`. For other durable behavior/contract changes, keep one `specs/changes/<name>.md` delta with only needed `ADD`, `MODIFY`, `REMOVE`, and/or `PRESERVE` sections.
-
-After editing specs, run:
-
-```bash
-charterleaf lint
-```
-
-`lint` checks structural conventions and deterministic active-change conflicts only. It does not judge writing, architecture quality, or semantic code/spec drift.
-
-After an accepted change is implemented, merge the durable result into living specs and delete the change file. Git keeps history.
-
-Do not plan, manage tasks, invoke agents, run implementation/review workflows, manage memory, or replace the host agent's code-navigation tools.
+If the CLI is not on PATH, use `node <skill-directory>/../../bin/charterleaf.js related <path>` or `lint`; the Extension supplies the absolute entry point. Report failed writing or validation accurately, and never relax a contract merely to remove an error.

package/skills/charterleaf/runtime.md

@@ -0,0 +1,11 @@
+# Charterleaf runtime
+
+Use constraints supplied with standard read results; do not load all specs or reread unchanged supplied bodies. A blocked write/edit requires inspecting the constraints or reading the named complete spec before retrying; never bypass it through another writer. Routing is a hint, not proof of coverage.
+
+Modes govern specs, not code: Auto maintains only justified durable knowledge; Confirm edits code normally and submits exact spec write/edit to the Extension's approval dialog (refusal/no UI: preserve spec, do not retry); Reference reports proposals/conflicts, never writes specs. Use standard write/edit only. Activation config is user-owned via /charterleaf. These guards are not a filesystem sandbox.
+
+A code/spec conflict is not permission to relax the spec. Fix implementation bugs; change contracts only with authoritative evidence or explicit accepted intent. Internal/refactor requests do not authorize changing return or ownership contracts. If a requested method violates an invariant, preserve spec/tests and ask for an explicit contract decision before coding. When uncertain, preserve the spec and report the conflict. Preserve user/parallel work; a touched file or dirty worktree does not prove line ownership. Never automatically revert, commit or push.
+
+## One final semantic review
+
+Only established, non-obvious, mistake-preventing contracts, invariants, boundaries, pitfalls or accepted decisions belong in specs. No durable change means no spec edit: exclude implementation summaries, tasks, progress, debugging and plans. At most one final review may follow development; do not start another cycle. Report task results/tests, not routine review bookkeeping. Spec writes receive structural lint, not semantic verification.

package/templates/change.md

@@ -5,6 +5,16 @@ affects:
 
 # <Change name>
 
+<!-- Optional staging. Use only when an accepted future contract must
+coexist with current living reality — implementation in another session or
+by another agent, human review first, or a multi-step migration.
+
+A change must contain at least one of ADD, MODIFY, or REMOVE.
+PRESERVE alone is not a change.
+
+After implementation, merge the durable result into living specs and
+delete this file. Git keeps history. -->
+
 ## Intent
 
 <What intentional behavior/contract change is being made, and why?>