discoclaw 0.1.0

package/dist/workspace-permissions.js

@@ -0,0 +1,134 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { KNOWN_TOOLS } from './config.js';
+const VALID_TIERS = new Set(['readonly', 'standard', 'full', 'custom']);
+export const MAX_NOTE_LENGTH = 500;
+export const TIER_TOOLS = {
+    readonly: ['Read', 'Glob', 'Grep', 'WebSearch', 'WebFetch'],
+    standard: ['Read', 'Edit', 'Glob', 'Grep', 'WebSearch', 'WebFetch'],
+    full: ['Bash', 'Read', 'Write', 'Edit', 'Glob', 'Grep', 'WebSearch', 'WebFetch'],
+};
+function validatedNote(obj, filePath, log) {
+    if (typeof obj.note !== 'string')
+        return {};
+    if (obj.note.length > MAX_NOTE_LENGTH) {
+        log?.warn?.({ filePath, length: obj.note.length, max: MAX_NOTE_LENGTH }, 'workspace-permissions: note exceeds max length, ignoring');
+        return {};
+    }
+    return { note: obj.note };
+}
+/**
+ * Load and validate workspace/PERMISSIONS.json. Returns null if the file
+ * doesn't exist or is invalid (with a warning logged for invalid files).
+ */
+export async function loadWorkspacePermissions(workspaceCwd, log) {
+    const filePath = path.join(workspaceCwd, 'PERMISSIONS.json');
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, 'utf-8');
+    }
+    catch {
+        return null; // File doesn't exist — use fallback.
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        log?.warn?.({ filePath }, 'workspace-permissions: invalid JSON, ignoring');
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        log?.warn?.({ filePath }, 'workspace-permissions: expected object, ignoring');
+        return null;
+    }
+    const obj = parsed;
+    if (typeof obj.tier !== 'string' || !VALID_TIERS.has(obj.tier)) {
+        log?.warn?.({ filePath, tier: obj.tier }, 'workspace-permissions: invalid tier, ignoring');
+        return null;
+    }
+    const tier = obj.tier;
+    if (tier === 'custom') {
+        if (!Array.isArray(obj.tools) || !obj.tools.every((t) => typeof t === 'string')) {
+            log?.warn?.({ filePath }, 'workspace-permissions: custom tier requires tools array, ignoring');
+            return null;
+        }
+        const tools = obj.tools;
+        if (tools.length === 0) {
+            log?.warn?.({ filePath }, 'workspace-permissions: custom tier has empty tools array');
+        }
+        const unknown = tools.filter((t) => !KNOWN_TOOLS.has(t));
+        if (unknown.length) {
+            log?.warn?.({ filePath, unknown }, 'workspace-permissions: unknown tool names');
+        }
+        return {
+            tier,
+            tools,
+            ...validatedNote(obj, filePath, log),
+        };
+    }
+    return {
+        tier,
+        ...validatedNote(obj, filePath, log),
+    };
+}
+/**
+ * Probe workspace/PERMISSIONS.json and return a discriminated result
+ * indicating whether the file is valid, missing, or invalid (with reason).
+ */
+export async function probeWorkspacePermissions(workspaceCwd) {
+    const filePath = path.join(workspaceCwd, 'PERMISSIONS.json');
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, 'utf-8');
+    }
+    catch {
+        return { status: 'missing' };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { status: 'invalid', reason: 'invalid JSON' };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return { status: 'invalid', reason: 'expected object' };
+    }
+    const obj = parsed;
+    if (typeof obj.tier !== 'string' || !VALID_TIERS.has(obj.tier)) {
+        return { status: 'invalid', reason: `invalid tier: ${JSON.stringify(obj.tier)}` };
+    }
+    const tier = obj.tier;
+    if (tier === 'custom') {
+        if (!Array.isArray(obj.tools) || !obj.tools.every((t) => typeof t === 'string')) {
+            return { status: 'invalid', reason: 'custom tier requires tools array' };
+        }
+        return {
+            status: 'valid',
+            permissions: {
+                tier,
+                tools: obj.tools,
+                ...validatedNote(obj, filePath),
+            },
+        };
+    }
+    return {
+        status: 'valid',
+        permissions: {
+            tier,
+            ...validatedNote(obj, filePath),
+        },
+    };
+}
+/**
+ * Resolve the effective tools array. Workspace permissions take precedence
+ * over the env-var-based tools list.
+ */
+export function resolveTools(permissions, envTools) {
+    if (!permissions)
+        return envTools;
+    if (permissions.tier === 'custom')
+        return permissions.tools ?? envTools;
+    return TIER_TOOLS[permissions.tier];
+}

package/dist/workspace-permissions.test.js

@@ -0,0 +1,181 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { loadWorkspacePermissions, probeWorkspacePermissions, resolveTools, MAX_NOTE_LENGTH } from './workspace-permissions.js';
+describe('loadWorkspacePermissions', () => {
+    const dirs = [];
+    afterEach(async () => {
+        for (const d of dirs) {
+            await fs.rm(d, { recursive: true, force: true });
+        }
+        dirs.length = 0;
+    });
+    function tmpDir() {
+        const p = fs.mkdtemp(path.join(os.tmpdir(), 'ws-perm-'));
+        p.then((d) => dirs.push(d));
+        return p;
+    }
+    it('returns null when file is missing', async () => {
+        const dir = await tmpDir();
+        expect(await loadWorkspacePermissions(dir)).toBeNull();
+    });
+    it('parses valid standard tier', async () => {
+        const dir = await tmpDir();
+        await fs.writeFile(path.join(dir, 'PERMISSIONS.json'), '{"tier":"standard"}');
+        const result = await loadWorkspacePermissions(dir);
+        expect(result).toEqual({ tier: 'standard' });
+    });
+    it('parses valid custom tier with tools', async () => {
+        const dir = await tmpDir();
+        await fs.writeFile(path.join(dir, 'PERMISSIONS.json'), '{"tier":"custom","tools":["Read","Edit"]}');
+        const result = await loadWorkspacePermissions(dir);
+        expect(result).toEqual({ tier: 'custom', tools: ['Read', 'Edit'] });
+    });
+    it('preserves optional note field', async () => {
+        const dir = await tmpDir();
+        await fs.writeFile(path.join(dir, 'PERMISSIONS.json'), '{"tier":"readonly","note":"No file changes."}');
+        const result = await loadWorkspacePermissions(dir);
+        expect(result).toEqual({ tier: 'readonly', note: 'No file changes.' });
+    });
+    it('returns null and warns on invalid JSON', async () => {
+        const dir = await tmpDir();
+        await fs.writeFile(path.join(dir, 'PERMISSIONS.json'), '{{bad');
+        const log = { warn: vi.fn() };
+        expect(await loadWorkspacePermissions(dir, log)).toBeNull();
+        expect(log.warn).toHaveBeenCalledOnce();
+    });
+    it('returns null and warns on invalid tier', async () => {
+        const dir = await tmpDir();
+        await fs.writeFile(path.join(dir, 'PERMISSIONS.json'), '{"tier":"godmode"}');
+        const log = { warn: vi.fn() };
+        expect(await loadWorkspacePermissions(dir, log)).toBeNull();
+        expect(log.warn).toHaveBeenCalledOnce();
+    });
+    it('returns null when custom tier lacks tools array', async () => {
+        const dir = await tmpDir();
+        await fs.writeFile(path.join(dir, 'PERMISSIONS.json'), '{"tier":"custom"}');
+        const log = { warn: vi.fn() };
+        expect(await loadWorkspacePermissions(dir, log)).toBeNull();
+        expect(log.warn).toHaveBeenCalledOnce();
+    });
+    it('custom tier with empty tools array parses and warns', async () => {
+        const dir = await tmpDir();
+        await fs.writeFile(path.join(dir, 'PERMISSIONS.json'), '{"tier":"custom","tools":[]}');
+        const log = { warn: vi.fn() };
+        const result = await loadWorkspacePermissions(dir, log);
+        expect(result).toEqual({ tier: 'custom', tools: [] });
+        expect(log.warn).toHaveBeenCalledOnce();
+    });
+    it('custom tier with unknown tool names parses and warns', async () => {
+        const dir = await tmpDir();
+        await fs.writeFile(path.join(dir, 'PERMISSIONS.json'), '{"tier":"custom","tools":["Read","NotARealTool"]}');
+        const log = { warn: vi.fn() };
+        const result = await loadWorkspacePermissions(dir, log);
+        expect(result).toEqual({ tier: 'custom', tools: ['Read', 'NotARealTool'] });
+        expect(log.warn).toHaveBeenCalledOnce();
+    });
+    it('omits note exceeding MAX_NOTE_LENGTH and warns', async () => {
+        const dir = await tmpDir();
+        const longNote = 'x'.repeat(MAX_NOTE_LENGTH + 1);
+        await fs.writeFile(path.join(dir, 'PERMISSIONS.json'), JSON.stringify({ tier: 'readonly', note: longNote }));
+        const log = { warn: vi.fn() };
+        const result = await loadWorkspacePermissions(dir, log);
+        expect(result).toEqual({ tier: 'readonly' });
+        expect(log.warn).toHaveBeenCalledOnce();
+    });
+    it('preserves note at exactly MAX_NOTE_LENGTH', async () => {
+        const dir = await tmpDir();
+        const note = 'x'.repeat(MAX_NOTE_LENGTH);
+        await fs.writeFile(path.join(dir, 'PERMISSIONS.json'), JSON.stringify({ tier: 'standard', note }));
+        const result = await loadWorkspacePermissions(dir);
+        expect(result).toEqual({ tier: 'standard', note });
+    });
+    it('accepts note containing newlines', async () => {
+        const dir = await tmpDir();
+        const note = 'line1\nline2\nline3';
+        await fs.writeFile(path.join(dir, 'PERMISSIONS.json'), JSON.stringify({ tier: 'readonly', note }));
+        const result = await loadWorkspacePermissions(dir);
+        expect(result).toEqual({ tier: 'readonly', note });
+    });
+});
+describe('probeWorkspacePermissions', () => {
+    const dirs = [];
+    afterEach(async () => {
+        for (const d of dirs) {
+            await fs.rm(d, { recursive: true, force: true });
+        }
+        dirs.length = 0;
+    });
+    function tmpDir() {
+        const p = fs.mkdtemp(path.join(os.tmpdir(), 'ws-probe-'));
+        p.then((d) => dirs.push(d));
+        return p;
+    }
+    it('returns missing when file does not exist', async () => {
+        const dir = await tmpDir();
+        const result = await probeWorkspacePermissions(dir);
+        expect(result).toEqual({ status: 'missing' });
+    });
+    it('returns invalid with reason for bad JSON', async () => {
+        const dir = await tmpDir();
+        await fs.writeFile(path.join(dir, 'PERMISSIONS.json'), '{{bad');
+        const result = await probeWorkspacePermissions(dir);
+        expect(result).toEqual({ status: 'invalid', reason: 'invalid JSON' });
+    });
+    it('returns invalid with reason for non-object', async () => {
+        const dir = await tmpDir();
+        await fs.writeFile(path.join(dir, 'PERMISSIONS.json'), '"just a string"');
+        const result = await probeWorkspacePermissions(dir);
+        expect(result).toEqual({ status: 'invalid', reason: 'expected object' });
+    });
+    it('returns invalid with reason for bad tier', async () => {
+        const dir = await tmpDir();
+        await fs.writeFile(path.join(dir, 'PERMISSIONS.json'), '{"tier":"godmode"}');
+        const result = await probeWorkspacePermissions(dir);
+        expect(result).toEqual({ status: 'invalid', reason: 'invalid tier: "godmode"' });
+    });
+    it('returns invalid when custom tier lacks tools array', async () => {
+        const dir = await tmpDir();
+        await fs.writeFile(path.join(dir, 'PERMISSIONS.json'), '{"tier":"custom"}');
+        const result = await probeWorkspacePermissions(dir);
+        expect(result).toEqual({ status: 'invalid', reason: 'custom tier requires tools array' });
+    });
+    it('returns valid with permissions for standard tier', async () => {
+        const dir = await tmpDir();
+        await fs.writeFile(path.join(dir, 'PERMISSIONS.json'), '{"tier":"standard"}');
+        const result = await probeWorkspacePermissions(dir);
+        expect(result).toEqual({ status: 'valid', permissions: { tier: 'standard' } });
+    });
+    it('returns valid with permissions for custom tier', async () => {
+        const dir = await tmpDir();
+        await fs.writeFile(path.join(dir, 'PERMISSIONS.json'), '{"tier":"custom","tools":["Read","Edit"]}');
+        const result = await probeWorkspacePermissions(dir);
+        expect(result).toEqual({ status: 'valid', permissions: { tier: 'custom', tools: ['Read', 'Edit'] } });
+    });
+    it('returns valid with note when present', async () => {
+        const dir = await tmpDir();
+        await fs.writeFile(path.join(dir, 'PERMISSIONS.json'), '{"tier":"readonly","note":"No writes."}');
+        const result = await probeWorkspacePermissions(dir);
+        expect(result).toEqual({ status: 'valid', permissions: { tier: 'readonly', note: 'No writes.' } });
+    });
+});
+describe('resolveTools', () => {
+    const envTools = ['Bash', 'Read', 'Write', 'Edit', 'Glob', 'Grep', 'WebSearch', 'WebFetch'];
+    it('returns env tools when permissions is null', () => {
+        expect(resolveTools(null, envTools)).toBe(envTools);
+    });
+    it('returns correct tools for readonly tier', () => {
+        expect(resolveTools({ tier: 'readonly' }, envTools)).toEqual(['Read', 'Glob', 'Grep', 'WebSearch', 'WebFetch']);
+    });
+    it('returns correct tools for standard tier', () => {
+        expect(resolveTools({ tier: 'standard' }, envTools)).toEqual(['Read', 'Edit', 'Glob', 'Grep', 'WebSearch', 'WebFetch']);
+    });
+    it('returns correct tools for full tier', () => {
+        expect(resolveTools({ tier: 'full' }, envTools)).toEqual(['Bash', 'Read', 'Write', 'Edit', 'Glob', 'Grep', 'WebSearch', 'WebFetch']);
+    });
+    it('uses custom tools array for custom tier', () => {
+        const custom = ['Read', 'WebSearch'];
+        expect(resolveTools({ tier: 'custom', tools: custom }, envTools)).toEqual(custom);
+    });
+});

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "discoclaw",
+  "version": "0.1.0",
+  "description": "Minimal Discord bridge routing messages to AI runtimes",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DiscoClaw/discoclaw.git"
+  },
+  "bin": {
+    "discoclaw": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist/",
+    "templates/",
+    "systemd/",
+    ".context/",
+    ".env.example",
+    ".env.example.full",
+    "scripts/cron/cron-tag-map.json",
+    "scripts/tasks/tag-map.json"
+  ],
+  "type": "module",
+  "packageManager": "pnpm@10.28.2",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "prepare": "simple-git-hooks",
+    "dev": "tsx src/index.ts",
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "discord:invite-url": "tsx scripts/discord-invite-url.ts",
+    "discord:smoke-test": "node scripts/discord-smoke-test.mjs",
+    "discord:join-threads": "node scripts/discord-join-threads.mjs",
+    "claude:install-skills": "tsx scripts/install-claude-skills.ts",
+    "sync:discord-context": "tsx scripts/sync-discord-context.ts",
+    "guard:legacy": "tsx scripts/legacy-token-guard.ts",
+    "preflight": "tsx scripts/doctor.ts",
+    "preflight:online": "tsx scripts/doctor.ts --check-connection",
+    "doctor": "tsx scripts/doctor.ts",
+    "doctor:online": "tsx scripts/doctor.ts --check-connection",
+    "setup": "tsx scripts/setup.ts",
+    "test": "vitest run --passWithNoTests",
+    "prepublishOnly": "pnpm build && pnpm test",
+    "review:sections": "tsx scripts/review-sections.ts"
+  },
+  "dependencies": {
+    "croner": "^10.0.1",
+    "discord.js": "^14.19.3",
+    "dotenv": "^16.4.5",
+    "execa": "^9.5.2",
+    "pino": "^9.7.0"
+  },
+  "simple-git-hooks": {
+    "pre-push": "pnpm build && pnpm test"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "simple-git-hooks"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.1",
+    "simple-git-hooks": "^2.13.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.9"
+  }
+}

package/scripts/cron/cron-tag-map.json

@@ -0,0 +1,9 @@
+{
+  "report": "",
+  "maintenance": "",
+  "monitor": "",
+  "hourly": "",
+  "daily": "",
+  "weekly": "",
+  "monthly": ""
+}

package/scripts/tasks/tag-map.json

@@ -0,0 +1,10 @@
+{
+  "feature": "1469352147605786634",
+  "bug": "1469352147865829456",
+  "chore": "1473884551016349910",
+  "docs": "1473884551842496634",
+  "blocked": "1469352147865829462",
+  "open": "1472818699126706393",
+  "in_progress": "1472818699126706394",
+  "closed": "1472818699126706395"
+}

package/systemd/discoclaw.service

@@ -0,0 +1,19 @@
+[Unit]
+Description=Discoclaw
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=%h/code/discoclaw
+# Keep secrets local; this file should exist on the host (not committed).
+EnvironmentFile=%h/code/discoclaw/.env
+# Build first: `pnpm build` (this service runs `dist/`).
+ExecStart=/usr/bin/node %h/code/discoclaw/dist/index.js
+Restart=on-failure
+RestartSec=15
+StartLimitIntervalSec=600
+StartLimitBurst=3
+
+[Install]
+WantedBy=default.target

package/templates/recipes/integration.discoclaw-recipe.md

@@ -0,0 +1,171 @@
+---
+spec_version: "1.0"
+plan_id: "replace-with-kebab-id"
+title: "Replace with clear integration title"
+author: "Your name or handle"
+source: "manual"
+license: "MIT"
+created_at: "2026-02-11T00:00:00Z"
+integration_type: "runtime"
+discoclaw_min_version: "0.1.0"
+risk_level: "low"
+---
+
+<!--
+Author instructions (remove before sharing):
+- Keep required headings exactly as written.
+- Use YAML frontmatter for metadata in all plans.
+- For low-risk plans, JSON contract blocks are recommended but optional.
+- For medium/high-risk plans, JSON contract blocks are required.
+-->
+
+# DiscoClaw Recipe
+
+## Metadata
+
+Canonical metadata lives in YAML frontmatter.
+
+Optional notes:
+
+- Distribution notes:
+- Ownership notes:
+
+## Use Case
+
+- Problem:
+- Who benefits:
+- What this unlocks for another DiscoClaw user:
+
+## Scope
+
+In scope:
+
+- Item 1
+- Item 2
+
+Out of scope:
+
+- Item A
+- Item B
+
+## Integration Contract
+
+`implementation_contract` JSON block (required for medium/high risk; recommended for low risk):
+
+```json
+{
+  "files_add": [
+    "path/to/new-file"
+  ],
+  "files_modify": [
+    "path/to/existing-file"
+  ],
+  "env_changes": [
+    {
+      "name": "ENV_VAR_NAME",
+      "required": false,
+      "default": "",
+      "description": "What this controls"
+    }
+  ],
+  "runtime_behavior_changes": [
+    "Describe visible behavior changes"
+  ],
+  "out_of_scope": [
+    "Non-goal"
+  ]
+}
+```
+
+If omitting JSON for low-risk plans, include equivalent prose for files, env/config, behavior, and out-of-scope.
+
+Local repo mapping:
+
+- Primary entrypoints:
+- Files that may differ by user setup:
+- Mapping notes for alternate layouts:
+
+Compatibility notes:
+
+- Minimum DiscoClaw version:
+- Known incompatibilities:
+- Backward-compatible fallback behavior:
+
+## Implementation Steps
+
+1. Step one with concrete file-level action.
+2. Step two with concrete file-level action.
+3. Step three with concrete file-level action.
+
+## Acceptance Tests
+
+`acceptance_contract` JSON block (required for medium/high risk; recommended for low risk):
+
+```json
+{
+  "scenarios": [
+    {
+      "name": "Happy path",
+      "type": "integration",
+      "steps": [
+        "Run action"
+      ],
+      "expected": [
+        "Expected outcome"
+      ]
+    }
+  ],
+  "required_checks": [
+    "pnpm build",
+    "pnpm test"
+  ]
+}
+```
+
+If omitting JSON for low-risk plans, include equivalent prose for scenarios and expected outcomes.
+
+Manual test notes:
+
+- Test account/channel assumptions:
+- Required fixtures or mock data:
+- Observability/log lines to verify:
+
+## Risk, Permissions, Rollback
+
+Risk rationale:
+
+- Why this is low/medium/high risk.
+
+Required permissions/capabilities:
+
+- Discord permissions:
+- Runtime tools/capabilities:
+- Env vars or secrets:
+
+Rollback plan:
+
+1. Revert files:
+2. Revert config/env:
+3. Restart/redeploy steps:
+4. Verification steps after rollback:
+
+## Handoff Prompt (Consumer Agent)
+
+Use this prompt when another DiscoClaw user asks their agent to implement this plan:
+
+```text
+Read this .discoclaw-recipe.md file and produce a decision-complete implementation checklist mapped to local repo files. Validate required headings, YAML frontmatter metadata, and risk-gated JSON contract requirements first. Do not start coding until explicitly asked.
+```
+
+## Changelog
+
+- 2026-02-11: Initial version.
+
+Human approval checklist:
+
+- [ ] Required headings are present.
+- [ ] YAML frontmatter metadata is complete.
+- [ ] Metadata includes author/source/license.
+- [ ] Risk, permissions, and rollback are explicit.
+- [ ] JSON contract blocks satisfy risk-level requirements.
+- [ ] Handoff prompt is included and clear.