devflow-kit 1.8.2 → 2.0.0

package/dist/core/observation-io.js

@@ -0,0 +1,50 @@
+import { promises as fs } from 'fs';
+import * as p from '@clack/prompts';
+import { writeFileAtomicExclusive } from './fs-atomic.js';
+import { loadAndCountObservations } from './observations.js';
+/**
+ * @file observation-io.ts
+ *
+ * File I/O for observations and user-facing warnings.
+ * Bridges the pure data module (observations.ts) with the filesystem.
+ *
+ * The `.md` files are a pure render of the decisions ledger — never edit them
+ * directly. To change the status of a decision or pitfall, use the
+ * `retire-anchor` op in `json-helper.cjs`, which flips `decisions_status` on
+ * the ledger row and re-renders both `.md` files atomically.
+ */
+/**
+ * Read and parse observations from a log file.
+ * Returns empty results if the file does not exist.
+ */
+export async function readObservations(logPath) {
+    try {
+        const logContent = await fs.readFile(logPath, 'utf-8');
+        return loadAndCountObservations(logContent);
+    }
+    catch {
+        return { observations: [], invalidCount: 0 };
+    }
+}
+/**
+ * Write observations back to a log file atomically.
+ * Each observation is serialized as a JSON line. Uses a `.tmp` sibling + rename so
+ * concurrent readers (e.g. background-learning during a race) never observe a
+ * half-written file. Delegates to `writeFileAtomicExclusive` in fs-atomic.ts
+ * (D34/D39: canonical TS atomic-write helper).
+ */
+export async function writeObservations(logPath, observations) {
+    const lines = observations.map(o => JSON.stringify(o));
+    const content = lines.join('\n') + (lines.length ? '\n' : '');
+    await writeFileAtomicExclusive(logPath, content);
+}
+/**
+ * Warn the user if invalid entries were found in a log file.
+ * Invalid entries are cleaned up automatically by the background curation pass.
+ */
+export function warnIfInvalid(invalidCount) {
+    if (invalidCount > 0) {
+        p.log.warn(`Note: ${invalidCount} invalid entry(ies) found. They will be cleaned up automatically.`);
+    }
+}
+//# sourceMappingURL=observation-io.js.map

package/dist/core/observations.js

@@ -0,0 +1,109 @@
+/**
+ * @file observations.ts
+ *
+ * Core observation type, type guard, parsing, and pure formatting.
+ * No I/O, no UI dependencies — pure data module.
+ */
+/**
+ * D201: Canonical status vocabulary for rendered decisions.md / pitfalls.md entries.
+ *
+ * Derived from an `as const` literal array so the union type, the runtime set,
+ * and the VALID_DECISIONS_STATUSES guard below are always in sync — no manual
+ * duplication. `Retired` is the output of the `retire-anchor` op and MUST be
+ * present; `Unknown` was never produced by any operation and has been removed.
+ *
+ * Defined here (pure data module) so both observation-io.ts and learning.ts
+ * can import without creating a utility→command circular dependency.
+ * Re-exported through src/cli/commands/learning.ts for external consumers.
+ * Consumed by LedgerRow (this file) and LearningObservation.decisions_status (this file).
+ */
+export const DECISIONS_ENTRY_STATUSES = [
+    'Accepted', 'Active', 'Deprecated', 'Superseded', 'Retired',
+];
+/** Valid values for the decisions_status optional field — derived from DECISIONS_ENTRY_STATUSES. */
+const VALID_DECISIONS_STATUSES = new Set(DECISIONS_ENTRY_STATUSES);
+/**
+ * Type guard for validating raw JSON as a LearningObservation.
+ * Accepts all 4 types (v2: decision + pitfall added) and all statuses including deprecated.
+ * New optional fields (anchor_id, date, decisions_status, amendments, raw_body) are
+ * validated when present but their absence never causes rejection — backward compatible.
+ */
+export function isLearningObservation(obj) {
+    if (typeof obj !== 'object' || obj === null)
+        return false;
+    const o = obj;
+    // Required fields
+    if (!(typeof o.id === 'string' && o.id.length > 0))
+        return false;
+    if (!(o.type === 'workflow' || o.type === 'procedural' || o.type === 'decision' || o.type === 'pitfall'))
+        return false;
+    if (!(typeof o.pattern === 'string' && o.pattern.length > 0))
+        return false;
+    if (typeof o.confidence !== 'number')
+        return false;
+    if (typeof o.observations !== 'number')
+        return false;
+    if (typeof o.first_seen !== 'string')
+        return false;
+    if (typeof o.last_seen !== 'string')
+        return false;
+    if (!(o.status === 'observing' || o.status === 'ready' || o.status === 'created' || o.status === 'deprecated'))
+        return false;
+    if (!Array.isArray(o.evidence))
+        return false;
+    if (typeof o.details !== 'string')
+        return false;
+    // Optional ledger fields: validate type when present, reject if wrong type
+    if (o.anchor_id !== undefined && typeof o.anchor_id !== 'string')
+        return false;
+    if (o.date !== undefined && typeof o.date !== 'string')
+        return false;
+    if (o.decisions_status !== undefined && !VALID_DECISIONS_STATUSES.has(o.decisions_status))
+        return false;
+    if (o.amendments !== undefined) {
+        if (!Array.isArray(o.amendments))
+            return false;
+        for (const a of o.amendments) {
+            if (typeof a !== 'object' || a === null)
+                return false;
+            const am = a;
+            if (typeof am.date !== 'string' || typeof am.note !== 'string')
+                return false;
+        }
+    }
+    if (o.raw_body !== undefined && typeof o.raw_body !== 'string')
+        return false;
+    return true;
+}
+/**
+ * Parse a JSONL learning log into typed observations.
+ * Skips empty and malformed lines.
+ */
+export function parseLearningLog(logContent) {
+    const observations = [];
+    for (const line of logContent.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (isLearningObservation(parsed)) {
+                observations.push(parsed);
+            }
+        }
+        catch {
+            // Skip malformed lines
+        }
+    }
+    return observations;
+}
+/**
+ * Parse a JSONL log and return valid observations plus the count of invalid entries.
+ * Centralises the raw-line-count + parse pattern used by --status, --list, and --purge.
+ */
+export function loadAndCountObservations(logContent) {
+    const rawLines = logContent.split('\n').filter(l => l.trim()).length;
+    const observations = parseLearningLog(logContent);
+    return { observations, invalidCount: rawLines - observations.length };
+}
+//# sourceMappingURL=observations.js.map

package/dist/core/orphan-sweep.js

@@ -0,0 +1,92 @@
+import { promises as fs } from 'fs';
+import * as path from 'path';
+/**
+ * @file orphan-sweep.ts
+ *
+ * Shared helper for registry-diff sweeps of installed asset directories.
+ * Used by both the install pipeline (installer.ts) and the uninstall pipeline
+ * (uninstall.ts) so the logic lives in exactly one place.
+ *
+ * Also exports the mdFileName / mdEntryName inverse pair for .md asset naming,
+ * mirroring the prefixSkillName / unprefixSkillName pair in plugins.ts.
+ */
+// ---------------------------------------------------------------------------
+// .md filename helpers — inverse pair
+// ---------------------------------------------------------------------------
+/**
+ * Convert a registry name to its .md filename.
+ * Inverse of {@link mdEntryName}.
+ *
+ * @example mdFileName('code') === 'code.md'
+ */
+export function mdFileName(name) {
+    return `${name}.md`;
+}
+/**
+ * Extract the registry name from a .md directory entry.
+ * Returns null for entries that are not .md files — suitable as a
+ * pass-through predicate for {@link sweepOrphanedAssets}.
+ * Inverse of {@link mdFileName}.
+ *
+ * @example mdEntryName('code.md') === 'code'
+ * @example mdEntryName('SKILL.md') === 'SKILL'
+ * @example mdEntryName('code.ts') === null
+ */
+export function mdEntryName(entry) {
+    return entry.endsWith('.md') ? entry.slice(0, -3) : null;
+}
+// ---------------------------------------------------------------------------
+// sweepOrphanedAssets
+// ---------------------------------------------------------------------------
+/**
+ * Remove entries from `dir` that are not present in the `knownNames` registry.
+ *
+ * Only removes entries that `extractRegistryName` accepts (returns non-null for);
+ * entries the predicate skips (returns null) are left completely untouched.
+ *
+ * @param dir - The install directory to sweep.
+ * @param knownNames - Full registry set spanning ALL plugins. Must cover the
+ *   complete installed universe — NOT intersected with any selected-plugin subset.
+ *   Assets from uninstalled plugins must survive a partial sweep.
+ * @param extractRegistryName - Maps a directory entry name to a registry key
+ *   (the name to look up in knownNames), or null to skip this entry entirely.
+ *   For agents and commands: use {@link mdEntryName}.
+ *   For skills: strip the devflow: prefix.
+ *
+ * @returns A {@link SweepResult} reporting how many entries were scanned, which
+ *   registry names were removed, and which removals failed.
+ *   `scanned` is the count matched by the predicate (not the removed count) —
+ *   use for non-vacuousness assertions in tests: a value of 0 means no entry
+ *   matched the predicate.
+ *
+ * Per-item failure isolation: both the outer readdir and the inner rm are
+ * independently try/caught — a missing directory is a no-op and a failed
+ * individual removal is recorded in `failed` without aborting the sweep (avoids PF-009).
+ * Never writes, only removes (avoids PF-011).
+ */
+export async function sweepOrphanedAssets(dir, knownNames, extractRegistryName) {
+    const removed = [];
+    const failed = [];
+    let scanned = 0;
+    try {
+        const entries = await fs.readdir(dir);
+        for (const entry of entries) {
+            const registryName = extractRegistryName(entry);
+            if (registryName === null)
+                continue;
+            scanned++;
+            if (!knownNames.has(registryName)) {
+                try {
+                    await fs.rm(path.join(dir, entry), { recursive: true, force: true });
+                    removed.push(registryName);
+                }
+                catch (err) {
+                    failed.push({ name: registryName, error: err }); /* per-item isolation (avoids PF-009) */
+                }
+            }
+        }
+    }
+    catch { /* directory absent or unreadable — not an error (avoids PF-009) */ }
+    return { scanned, removed, failed };
+}
+//# sourceMappingURL=orphan-sweep.js.map

package/dist/core/paths.js

@@ -0,0 +1,48 @@
+import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join, relative, isAbsolute, resolve } from 'path';
+/**
+ * Returns true when `candidate`, resolved relative to `parent`, is strictly
+ * contained within `parent` — i.e., it is not the parent itself, does not
+ * escape via `..` traversal, and is not an absolute path that lands outside.
+ *
+ * Pure function — no filesystem access.
+ *
+ * Used by reapplyAgentMapping to guard against path-traversal mapping keys.
+ *
+ * @example isContainedIn('/a', 'b')       === true
+ * @example isContainedIn('/a', '../b')    === false
+ * @example isContainedIn('/a', '/b')      === false
+ * @example isContainedIn('/a', '')        === false
+ * @example isContainedIn('/a', '.')       === false  (same as parent)
+ */
+export function isContainedIn(parent, candidate) {
+    if (candidate === '')
+        return false;
+    const resolvedParent = resolve(parent);
+    const resolvedCandidate = resolve(resolvedParent, candidate);
+    const rel = relative(resolvedParent, resolvedCandidate);
+    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+}
+/**
+ * D-paths: single package-root resolver used by everything that previously did
+ * scattered path.resolve(__dirname, '../..') lookups.
+ *
+ * From compiled dist/core/paths.js, root is 2 levels up from __dirname.
+ * From source src/core/paths.ts under vitest/tsx, root is also 2 levels up.
+ *
+ * Throws loudly if package.json is not found at the resolved root — dist-depth
+ * bugs become loud errors, never silent wrong-path lookups.
+ */
+export function getPackageRoot() {
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = dirname(__filename);
+    const root = resolve(__dirname, '../..');
+    if (!existsSync(join(root, 'package.json'))) {
+        throw new Error(`getPackageRoot: package.json not found at resolved root "${root}". ` +
+            `This indicates a depth mismatch in the compiled output ` +
+            `(expected dist/core/paths.js to be 2 levels below repo root).`);
+    }
+    return root;
+}
+//# sourceMappingURL=paths.js.map