@orderful/droid 0.45.1 → 0.47.0

package/src/tools/pii/skills/pii/scripts/presidio.test.ts

@@ -0,0 +1,444 @@
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
+import { spawnSync } from 'child_process';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+/**
+ * Integration tests for presidio scripts.
+ *
+ * These tests validate argument parsing, error paths, and JSON output shape.
+ * They do NOT invoke Presidio/Python directly — all Python-dependent paths
+ * are gated by existsSync checks in the scripts, so tests run without Python.
+ */
+
+const SCRIPTS_DIR = __dirname;
+
+interface ScriptResult {
+  success: boolean;
+  already_existed?: boolean;
+  initialized?: boolean;
+  python_path?: string;
+  venv_path?: string;
+  entities?: Array<{ type: string; start: number; end: number; score: number; line: number; text?: string }>;
+  dry_run?: boolean;
+  original_path?: string;
+  output_path?: string;
+  entities_found?: number;
+  entities_redacted?: number;
+  redacted_text?: string;
+  error?: string;
+  init_required?: boolean;
+}
+
+function runScript(scriptName: string, args: string[]): ScriptResult {
+  const scriptPath = join(SCRIPTS_DIR, `${scriptName}.ts`);
+
+  const result = spawnSync('bun', ['run', scriptPath, ...args], {
+    encoding: 'utf-8',
+    cwd: process.cwd(),
+  });
+
+  if (result.error) {
+    return { success: false, error: result.error.message };
+  }
+
+  try {
+    return JSON.parse(result.stdout.trim());
+  } catch {
+    return {
+      success: false,
+      error: `Failed to parse output: ${result.stdout}\nStderr: ${result.stderr}`,
+    };
+  }
+}
+
+function createFakeVenvWithPython(tempHome: string, scriptContent: string): string {
+  const venvPath = join(tempHome, '.droid', 'runtimes', 'presidio');
+  const binDir = join(venvPath, 'bin');
+  mkdirSync(binDir, { recursive: true });
+  writeFileSync(join(binDir, 'python3'), scriptContent, { mode: 0o755 });
+  return venvPath;
+}
+
+// ─── presidio-init ───────────────────────────────────────────────────────────
+
+describe('presidio-init', () => {
+  let tempHome: string;
+  let originalHome: string;
+
+  beforeEach(() => {
+    originalHome = process.env.HOME || '';
+    tempHome = mkdtempSync(join(tmpdir(), 'pii-test-home-'));
+    process.env.HOME = tempHome;
+  });
+
+  afterEach(() => {
+    process.env.HOME = originalHome;
+    try {
+      rmSync(tempHome, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  });
+
+  it('returns already_existed:true when marker file and venv binary both exist', () => {
+    // Pre-create the venv structure
+    const venvPath = join(tempHome, '.droid', 'runtimes', 'presidio');
+    const binDir = join(venvPath, 'bin');
+    mkdirSync(binDir, { recursive: true });
+    writeFileSync(join(venvPath, '.droid-initialized'), new Date().toISOString());
+    writeFileSync(join(binDir, 'python3'), '#!/bin/bash\necho "Python 3.9.0"', { mode: 0o755 });
+
+    const result = spawnSync(
+      'bun',
+      ['run', join(SCRIPTS_DIR, 'presidio-init.ts')],
+      {
+        encoding: 'utf-8',
+        env: { ...process.env, HOME: tempHome },
+      }
+    );
+
+    let parsed: ScriptResult;
+    try {
+      parsed = JSON.parse(result.stdout.trim());
+    } catch {
+      parsed = { success: false, error: `Parse error: ${result.stdout}` };
+    }
+
+    expect(parsed.success).toBe(true);
+    expect(parsed.already_existed).toBe(true);
+  });
+
+  it('returns success:false with clear error when python3 is not available', () => {
+    // Override PATH to have no python3
+    const result = spawnSync(
+      'bun',
+      ['run', join(SCRIPTS_DIR, 'presidio-init.ts')],
+      {
+        encoding: 'utf-8',
+        env: { ...process.env, HOME: tempHome, PATH: '/nonexistent' },
+      }
+    );
+
+    let parsed: ScriptResult;
+    try {
+      parsed = JSON.parse(result.stdout.trim());
+    } catch {
+      // If Python is truly not found, the error may be in stderr
+      parsed = { success: false, error: 'python3 not found' };
+    }
+
+    expect(parsed.success).toBe(false);
+    expect(parsed.error).toBeDefined();
+  });
+});
+
+// ─── presidio-analyze ────────────────────────────────────────────────────────
+
+describe('presidio-analyze', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'pii-analyze-test-'));
+  });
+
+  afterEach(() => {
+    try {
+      rmSync(tempDir, { recursive: true, force: true });
+    } catch {
+      // Ignore
+    }
+  });
+
+  it('returns success:false with init_required when venv does not exist', () => {
+    const result = spawnSync(
+      'bun',
+      ['run', join(SCRIPTS_DIR, 'presidio-analyze.ts'), '--file', join(tempDir, 'test.md')],
+      {
+        encoding: 'utf-8',
+        env: { ...process.env, HOME: join(tempDir, 'nonexistent-home') },
+      }
+    );
+
+    let parsed: ScriptResult;
+    try {
+      parsed = JSON.parse(result.stdout.trim());
+    } catch {
+      parsed = { success: false, error: `Parse error: ${result.stdout}` };
+    }
+
+    expect(parsed.success).toBe(false);
+    expect(parsed.init_required).toBe(true);
+    expect(parsed.error).toContain('presidio-init');
+  });
+
+  it('returns success:false when neither --file nor --text is provided', () => {
+    // Use a fake home so venv won't be found — still validates arg parsing
+    const result = spawnSync(
+      'bun',
+      ['run', join(SCRIPTS_DIR, 'presidio-analyze.ts')],
+      {
+        encoding: 'utf-8',
+        env: { ...process.env, HOME: join(tempDir, 'nonexistent-home') },
+      }
+    );
+
+    let parsed: ScriptResult;
+    try {
+      parsed = JSON.parse(result.stdout.trim());
+    } catch {
+      parsed = { success: false, error: `Parse error: ${result.stdout}` };
+    }
+
+    // Either init_required or missing arg error — both are valid failures
+    expect(parsed.success).toBe(false);
+    expect(parsed.error).toBeDefined();
+  });
+
+  it('returns success:false when --file does not exist (and venv exists)', () => {
+    // Pre-create a fake venv so the script gets past the venv check
+    const fakeHome = join(tempDir, 'fake-home');
+    createFakeVenvWithPython(fakeHome, '#!/bin/bash\necho ""');
+
+    const nonExistentFile = join(tempDir, 'does-not-exist.md');
+
+    const result = spawnSync(
+      'bun',
+      ['run', join(SCRIPTS_DIR, 'presidio-analyze.ts'), '--file', nonExistentFile],
+      {
+        encoding: 'utf-8',
+        env: { ...process.env, HOME: fakeHome },
+      }
+    );
+
+    let parsed: ScriptResult;
+    try {
+      parsed = JSON.parse(result.stdout.trim());
+    } catch {
+      parsed = { success: false, error: `Parse error: ${result.stdout}` };
+    }
+
+    expect(parsed.success).toBe(false);
+    expect(parsed.error).toContain('not found');
+  });
+
+  it('rejects invalid entity names before invoking Python', () => {
+    const fakeHome = join(tempDir, 'fake-home');
+    createFakeVenvWithPython(fakeHome, '#!/bin/bash\necho \'[]\'');
+
+    const result = spawnSync(
+      'bun',
+      [
+        'run',
+        join(SCRIPTS_DIR, 'presidio-analyze.ts'),
+        '--text',
+        'Call me at 555-1234',
+        '--entities',
+        'EMAIL_ADDRESS,__import__("os").system("whoami")',
+      ],
+      {
+        encoding: 'utf-8',
+        env: { ...process.env, HOME: fakeHome },
+      }
+    );
+
+    const parsed = JSON.parse(result.stdout.trim()) as ScriptResult;
+    expect(parsed.success).toBe(false);
+    expect(parsed.error).toContain('Invalid entity type');
+  });
+
+  it('does not include raw text in analyzer output entities', () => {
+    const fakeHome = join(tempDir, 'fake-home-no-text');
+    createFakeVenvWithPython(
+      fakeHome,
+      `#!/bin/bash
+if grep -q "'text': text\\[r.start:r.end\\]" "$1"; then
+  echo '[{"type":"EMAIL_ADDRESS","start":11,"end":27,"score":0.99,"text":"jane@example.com"}]'
+else
+  echo '[{"type":"EMAIL_ADDRESS","start":11,"end":27,"score":0.99}]'
+fi`,
+    );
+
+    const result = spawnSync(
+      'bun',
+      ['run', join(SCRIPTS_DIR, 'presidio-analyze.ts'), '--text', 'Contact me: jane@example.com'],
+      {
+        encoding: 'utf-8',
+        env: { ...process.env, HOME: fakeHome },
+      }
+    );
+
+    const parsed = JSON.parse(result.stdout.trim()) as ScriptResult;
+    expect(parsed.success).toBe(true);
+    expect(parsed.entities?.[0]?.type).toBe('EMAIL_ADDRESS');
+    expect(parsed.entities?.[0]).not.toHaveProperty('text');
+  });
+});
+
+// ─── presidio-redact ─────────────────────────────────────────────────────────
+
+describe('presidio-redact', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'pii-redact-test-'));
+  });
+
+  afterEach(() => {
+    try {
+      rmSync(tempDir, { recursive: true, force: true });
+    } catch {
+      // Ignore
+    }
+  });
+
+  it('returns success:false when --file is missing', () => {
+    const result = spawnSync(
+      'bun',
+      ['run', join(SCRIPTS_DIR, 'presidio-redact.ts')],
+      {
+        encoding: 'utf-8',
+        env: { ...process.env, HOME: join(tempDir, 'nonexistent-home') },
+      }
+    );
+
+    let parsed: ScriptResult;
+    try {
+      parsed = JSON.parse(result.stdout.trim());
+    } catch {
+      parsed = { success: false, error: `Parse error: ${result.stdout}` };
+    }
+
+    expect(parsed.success).toBe(false);
+    // Either init_required or missing --file error
+    expect(parsed.error).toBeDefined();
+  });
+
+  it('returns success:false with init_required when venv does not exist', () => {
+    const testFile = join(tempDir, 'test.md');
+    writeFileSync(testFile, 'Hello, my email is test@example.com');
+
+    const result = spawnSync(
+      'bun',
+      ['run', join(SCRIPTS_DIR, 'presidio-redact.ts'), '--file', testFile],
+      {
+        encoding: 'utf-8',
+        env: { ...process.env, HOME: join(tempDir, 'nonexistent-home') },
+      }
+    );
+
+    let parsed: ScriptResult;
+    try {
+      parsed = JSON.parse(result.stdout.trim());
+    } catch {
+      parsed = { success: false, error: `Parse error: ${result.stdout}` };
+    }
+
+    expect(parsed.success).toBe(false);
+    expect(parsed.init_required).toBe(true);
+    expect(parsed.error).toContain('presidio-init');
+  });
+
+  it('does not write output file with --dry-run (venv missing path)', () => {
+    const testFile = join(tempDir, 'test.md');
+    writeFileSync(testFile, 'Hello, my email is test@example.com');
+    const expectedOutput = join(tempDir, 'test-redacted.md');
+
+    const result = spawnSync(
+      'bun',
+      ['run', join(SCRIPTS_DIR, 'presidio-redact.ts'), '--file', testFile, '--dry-run'],
+      {
+        encoding: 'utf-8',
+        env: { ...process.env, HOME: join(tempDir, 'nonexistent-home') },
+      }
+    );
+
+    // With no venv, it will fail before writing
+    expect(existsSync(expectedOutput)).toBe(false);
+
+    let parsed: ScriptResult;
+    try {
+      parsed = JSON.parse(result.stdout.trim());
+    } catch {
+      parsed = { success: false, error: `Parse error: ${result.stdout}` };
+    }
+    expect(parsed.success).toBe(false);
+    expect(parsed.init_required).toBe(true);
+  });
+
+  it('correctly parses --output path argument', () => {
+    const testFile = join(tempDir, 'source.md');
+    writeFileSync(testFile, 'Contact: jane@example.com');
+    const customOutput = join(tempDir, 'custom-output.md');
+
+    // Without venv this will fail, but we can check the argument is parsed
+    const result = spawnSync(
+      'bun',
+      ['run', join(SCRIPTS_DIR, 'presidio-redact.ts'), '--file', testFile, '--output', customOutput],
+      {
+        encoding: 'utf-8',
+        env: { ...process.env, HOME: join(tempDir, 'nonexistent-home') },
+      }
+    );
+
+    let parsed: ScriptResult;
+    try {
+      parsed = JSON.parse(result.stdout.trim());
+    } catch {
+      parsed = { success: false, error: `Parse error: ${result.stdout}` };
+    }
+
+    // With no venv this will fail with init_required
+    expect(parsed.success).toBe(false);
+    expect(parsed.init_required).toBe(true);
+    // Confirm the output file was NOT created
+    expect(existsSync(customOutput)).toBe(false);
+  });
+
+  it('omits redacted_text in non-dry-run output', () => {
+    const fakeHome = join(tempDir, 'fake-home-no-redacted-text');
+    createFakeVenvWithPython(fakeHome, '#!/bin/bash\necho \'{"redacted_text":"masked text","entities_found":1,"entities_redacted":1}\'');
+
+    const testFile = join(tempDir, 'source.md');
+    const outputFile = join(tempDir, 'source-redacted.md');
+    writeFileSync(testFile, 'Contact: jane@example.com');
+
+    const result = spawnSync(
+      'bun',
+      ['run', join(SCRIPTS_DIR, 'presidio-redact.ts'), '--file', testFile],
+      {
+        encoding: 'utf-8',
+        env: { ...process.env, HOME: fakeHome },
+      }
+    );
+
+    const parsed = JSON.parse(result.stdout.trim()) as ScriptResult;
+    expect(parsed.success).toBe(true);
+    expect(parsed.dry_run).toBe(false);
+    expect(parsed.redacted_text).toBeUndefined();
+    expect(parsed.output_path).toBe(outputFile);
+    expect(existsSync(outputFile)).toBe(true);
+  });
+
+  it('rejects unsupported entity names', () => {
+    const fakeHome = join(tempDir, 'fake-home');
+    createFakeVenvWithPython(fakeHome, '#!/bin/bash\necho \'{"redacted_text":"ok","entities_found":0,"entities_redacted":0}\'');
+
+    const testFile = join(tempDir, 'source.md');
+    writeFileSync(testFile, 'Contact: jane@example.com');
+
+    const result = spawnSync(
+      'bun',
+      ['run', join(SCRIPTS_DIR, 'presidio-redact.ts'), '--file', testFile, '--entities', 'NOT_A_REAL_ENTITY'],
+      {
+        encoding: 'utf-8',
+        env: { ...process.env, HOME: fakeHome },
+      }
+    );
+
+    const parsed = JSON.parse(result.stdout.trim()) as ScriptResult;
+    expect(parsed.success).toBe(false);
+    expect(parsed.error).toContain('Unsupported entity type');
+  });
+});

package/src/tools/project/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "droid-project",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "description": "Manage project context files for persistent AI memory across sessions. Load, update, or create project context before working on multi-session features.",
   "author": {
     "name": "Orderful",

package/src/tools/project/TOOL.yaml

@@ -1,6 +1,6 @@
 name: project
 description: "Manage project context files for persistent AI memory across sessions. Load, update, or create project context before working on multi-session features."
-version: 0.3.6
+version: 0.4.0
 status: beta
 
 includes:
@@ -21,7 +21,7 @@ config_schema:
     required: true
   preset:
     type: select
-    description: Output format for templates
+    description: "Link style: obsidian uses [[wikilinks]], markdown uses [standard](links)"
     default: "markdown"
     options:
       - markdown

package/src/tools/project/skills/project/SKILL.md

@@ -7,7 +7,7 @@ allowed-tools: [Read, Write, Glob, Grep, Bash]
 
 # Project Skill
 
-Persistent project context that survives across sessions. Projects are folders containing `PROJECT.md` + `CHANGELOG.md`.
+Persistent project context that survives across sessions. Projects are folders containing `PROJECT.md` + `CHANGELOG.md`, with optional companion docs (`DECISIONS.md`, `WORKLOG.md`) that emerge as the project grows.
 
 ## Why Projects?
 
@@ -31,7 +31,7 @@ Chat history disappears. Projects persist.
 | Setting        | Default      | Description                                        |
 | -------------- | ------------ | -------------------------------------------------- |
 | `projects_dir` | **required** | Where projects are stored (must be configured)     |
-| `preset`       | `markdown`   | Output format: `markdown` or `obsidian`            |
+| `preset`       | `markdown`   | Link style: `obsidian` uses `[[wikilinks]]`, `markdown` uses `[standard](links)` |
 | `override`     | (none)       | User-defined behaviour overrides                   |
 
 **Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides.
@@ -106,6 +106,7 @@ Projects work best in a cycle:
 3. **Document** - Capture decisions in PROJECT.md before implementing
 4. **Implement** - Build with full context of why decisions were made
 5. **Capture** - `/project update` saves new learnings
-6. **Repeat** - Next session starts with accumulated knowledge
+6. **Prune** - If PROJECT.md exceeds ~300 lines, archive completed work to WORKLOG.md
+7. **Repeat** - Next session starts with accumulated knowledge
 
 Each cycle starts further ahead than the last.

package/src/tools/project/skills/project/references/changelog.md

@@ -5,7 +5,7 @@ Projects use a split file pattern to minimize context usage when loading.
 ## File Structure
 
 - `CHANGELOG.md` (sibling to PROJECT.md) - Complete version history
-- `PROJECT.md` - Only 3 most recent entries + link to full history
+- `PROJECT.md` - Link to full history only (version number lives in the metadata table)
 
 ## On Update
 
@@ -15,8 +15,8 @@ Projects use a split file pattern to minimize context usage when loading.
 2. **Add new entry to CHANGELOG.md** (prepend after header)
 
 3. **Update PROJECT.md changelog section**
-   - Keep only 3 most recent entries
-   - Ensure link to full history exists
+   - Keep only a link to CHANGELOG.md — no inline entries
+   - The version number in the metadata table is the quick-glance indicator
 
 ## CHANGELOG.md Format
 
@@ -35,31 +35,20 @@ All notable changes to the {Project Name} project.
 
 ## PROJECT.md Changelog Section Format
 
-**Markdown preset:**
 ```markdown
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
-
-### X.Y.Z - YYYY-MM-DD
-- [Most recent]
-
-### X.Y.Z - YYYY-MM-DD
-- [Second most recent]
-
-### X.Y.Z - YYYY-MM-DD
-- [Third most recent]
 ```
 
-**Obsidian preset:**
-```markdown
-## Changelog
+When `preset` is `obsidian`, use `See [[CHANGELOG|full history]].` instead.
 
-See [[CHANGELOG|full history]].
+## Migration
 
-### X.Y.Z - YYYY-MM-DD
-- [Most recent]
-```
+If an existing PROJECT.md has inline changelog entries:
+1. Ensure all entries exist in CHANGELOG.md
+2. Replace the inline entries with just the link
+3. This happens naturally during `/project update` — no need to proactively migrate
 
 ## Guidelines
 
@@ -67,4 +56,4 @@ See [[CHANGELOG|full history]].
 - Keep entries concise but descriptive
 - Group related changes in a single bullet when appropriate
 - Most recent version at the top
-- Use `##` headers in CHANGELOG.md, `###` in PROJECT.md
+- Use `##` headers in CHANGELOG.md

package/src/tools/project/skills/project/references/creating.md

@@ -7,7 +7,6 @@
 1. **Read config first**
    - Run `droid config --get tools.project` and parse the JSON output
    - Use `projects_dir` (required - if not configured, inform user to set it up)
-   - Use `preset` if configured (markdown or obsidian)
 
 2. **Get project name**
    - Use provided name, or ask if not provided
@@ -21,7 +20,6 @@
 4. **Create files from templates** (see `templates.md`)
    - `PROJECT.md` - Main context file
    - `CHANGELOG.md` - Version history
-   - Format varies by `preset` config (markdown vs obsidian)
 
 5. **Confirm creation**
    - Show created folder path
@@ -62,6 +60,18 @@ New projects start minimal and grow organically. Common sections added over time
 
 See `templates.md` for the full initial template.
 
+### Companion Docs
+
+Projects may grow companion docs over time. These are **never** created at project creation — they emerge as the project grows.
+
+| Doc | Created When | Purpose |
+|-----|-------------|---------|
+| `CHANGELOG.md` | At project creation (the one exception) | Version history |
+| `DECISIONS.md` | 3+ decisions accumulate in PROJECT.md | Dedicated decisions log |
+| `WORKLOG.md` | PROJECT.md exceeds ~300 lines with completed items | Archive of completed work |
+
+The `/project update` procedure handles creation and migration automatically — see `updating.md` for details.
+
 ---
 
 ## Creating from Codex

package/src/tools/project/skills/project/references/loading.md

@@ -32,7 +32,8 @@
    - Confirm which project was loaded
    - Summarize key context (2-3 sentences)
    - Use project contents for all subsequent work in the session
-   - **Do NOT read CHANGELOG.md** — it exists for on-demand lookup only. PROJECT.md already references it; that is enough context.
+   - **Do NOT read companion docs by default** — CHANGELOG.md, DECISIONS.md, and WORKLOG.md exist for on-demand lookup only. PROJECT.md already references them; that is enough context.
+   - If the user asks about decisions, past work, or history, THEN read the relevant companion doc.
 
 7. **If `-- {instruction}` provided:** Execute the follow-up instruction against the loaded project