@orderful/droid 0.45.1 → 0.46.0

package/dist/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orderful/droid",
-  "version": "0.45.1",
+  "version": "0.46.0",
   "description": "AI workflow toolkit for sharing skills, commands, and agents across the team",
   "type": "module",
   "bin": {

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

@@ -0,0 +1,25 @@
+{
+  "name": "droid-pii",
+  "version": "0.1.0",
+  "description": "Detect and redact PII (personally identifiable information) in text files. Powered by Microsoft Presidio with a bundled Python venv — zero external dependencies after first run.",
+  "author": {
+    "name": "Orderful",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai",
+    "pii"
+  ],
+  "skills": [
+    "./skills/pii/SKILL.md"
+  ],
+  "commands": [
+    "./commands/pii.md"
+  ],
+  "agents": [
+    "./agents/pii-scanner.md"
+  ]
+}

package/src/tools/pii/TOOL.yaml

@@ -0,0 +1,22 @@
+name: pii
+description: "Detect and redact PII (personally identifiable information) in text files. Powered by Microsoft Presidio with a bundled Python venv — zero external dependencies after first run."
+version: 0.1.0
+status: beta
+
+includes:
+  skills:
+    - name: pii
+      required: true
+  commands:
+    - name: pii
+      is_alias: false
+  agents:
+    - pii-scanner
+
+dependencies: []
+
+prerequisites:
+  - name: python3
+    description: "Python 3.8+ required to run the Presidio venv"
+    check: "python3 --version"
+    install_hint: "Install Python 3 from python.org or via: brew install python3"

package/src/tools/pii/agents/pii-scanner.md

@@ -0,0 +1,85 @@
+---
+name: pii-scanner
+description: "Isolated PII analysis agent. Runs presidio-analyze.ts in a contained context so raw entity values never appear in the parent conversation. Use PROACTIVELY when the pii skill delegates scan operations."
+tools:
+  - Bash
+color: orange
+---
+
+You are a PII scanning agent. Your sole job is to run `presidio-analyze.ts` on a file or text and return a structured summary — without leaking raw PII values into the conversation.
+
+## Inputs
+
+You will receive:
+
+1. `file_path` — absolute path to the file to scan (preferred), OR
+2. `text_content` — inline text to scan (for small strings only)
+3. `entities` (optional) — comma-separated list of entity types to filter (e.g. `EMAIL_ADDRESS,PHONE_NUMBER`)
+4. `venv_path` (optional) — override for the Presidio venv path (default: `~/.droid/runtimes/presidio/`)
+
+## Rules
+
+- **Never echo raw PII values** in your output — return entity types, counts, and line numbers only
+- Make exactly one Bash call to `presidio-analyze.ts`
+- Parse the JSON result and return only the structured summary
+- If the script returns `init_required: true`, stop and tell the parent skill to run `presidio-init.ts` first
+- If the file does not exist, return a clear error
+
+## Procedure
+
+1. Build the command:
+   ```bash
+   droid exec pii presidio-analyze --file <file_path> [--entities <types>]
+   ```
+   (Use `--text` only for inline strings under ~1000 characters)
+
+2. Parse the JSON output from the script
+
+3. From the `entities` array, compute:
+   - `total_entities`: total count
+   - `by_type`: entity type → count map
+   - `lines_affected`: sorted unique list of line numbers
+   - `sample_lines`: up to 5 line numbers with the entity types found on each line
+
+4. Return the structured summary (see Output Format below)
+
+## Output Format
+
+Return JSON:
+
+```json
+{
+  "file": "/path/to/file.md",
+  "total_entities": 3,
+  "by_type": {
+    "EMAIL_ADDRESS": 2,
+    "PHONE_NUMBER": 1
+  },
+  "lines_affected": [4, 8, 12],
+  "sample_lines": [
+    { "line": 4, "types": ["EMAIL_ADDRESS"] },
+    { "line": 8, "types": ["PHONE_NUMBER"] },
+    { "line": 12, "types": ["EMAIL_ADDRESS"] }
+  ]
+}
+```
+
+If no entities are found:
+```json
+{
+  "file": "/path/to/file.md",
+  "total_entities": 0,
+  "by_type": {},
+  "lines_affected": [],
+  "sample_lines": []
+}
+```
+
+If an error occurs:
+```json
+{
+  "file": "/path/to/file.md",
+  "error": "...",
+  "init_required": true
+}
+```

package/src/tools/pii/commands/pii.md

@@ -0,0 +1,33 @@
+---
+name: pii
+description: "Detect and redact PII (personally identifiable information) in files and directories. Powered by Microsoft Presidio."
+argument-hint: "[scan | redact] {file|dir} [--entities TYPES] [--output PATH] [--dry-run] [--mask]"
+---
+
+# /pii
+
+**User invoked:** `/pii $ARGUMENTS`
+
+**Your task:** Invoke the **pii skill** with these arguments.
+
+## Examples
+
+- `/pii scan transcript.md`
+- `/pii scan ./meeting-notes/`
+- `/pii redact transcript.md --output transcript-clean.md`
+- `/pii redact transcript.md --dry-run`
+- `/pii redact transcript.md --entities PHONE_NUMBER,EMAIL_ADDRESS`
+
+## Quick Reference
+
+```bash
+/pii scan {file}                              # Scan file for PII
+/pii scan {dir}                               # Scan directory recursively
+/pii redact {file}                            # Redact PII (writes {file}-redacted.{ext})
+/pii redact {file} --output {out}             # Redact to specific output path
+/pii redact {file} --dry-run                  # Preview redactions without writing
+/pii redact {file} --entities TYPES           # Redact only specific entity types
+/pii redact {file} --mask                     # Use *** instead of <ENTITY_TYPE>
+```
+
+See the **pii skill** for full behaviour, procedure, and supported entity types.