clawmini 0.0.8 → 0.0.9

package/src/shared/template-manifest.ts

@@ -0,0 +1,267 @@
+import fs from 'node:fs';
+import fsPromises from 'node:fs/promises';
+import path from 'node:path';
+import { createHash, randomBytes } from 'node:crypto';
+import { z } from 'zod';
+
+export type FileMode = 'track' | 'seed-once';
+
+const TemplateManifestSchema = z.looseObject({
+  files: z.record(z.string(), z.enum(['track', 'seed-once'])).optional(),
+});
+
+export type TemplateManifest = z.infer<typeof TemplateManifestSchema>;
+
+const InstalledFilesSchema = z.looseObject({
+  files: z
+    .record(
+      z.string(),
+      z.looseObject({
+        sha: z.string(),
+      })
+    )
+    .optional(),
+});
+
+export type InstalledFiles = z.infer<typeof InstalledFilesSchema>;
+
+export function sha256(content: string | Buffer): string {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+export async function fileSha(filePath: string): Promise<string | null> {
+  try {
+    const buf = await fsPromises.readFile(filePath);
+    return sha256(buf);
+  } catch {
+    return null;
+  }
+}
+
+export async function readTemplateManifest(templateDir: string): Promise<TemplateManifest | null> {
+  const manifestPath = path.join(templateDir, 'template.json');
+  try {
+    const raw = await fsPromises.readFile(manifestPath, 'utf-8');
+    const parsed = TemplateManifestSchema.safeParse(JSON.parse(raw));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+
+// Resolve the manifest mode for a given relative path. Exact entries win; if
+// no exact match, walk the prefix directory entries (longest first). Fallback
+// is the provided default mode.
+export function getFileMode(
+  relPath: string,
+  manifest: TemplateManifest | null,
+  defaultMode: FileMode
+): FileMode {
+  if (!manifest?.files) return defaultMode;
+  const normalized = relPath.split(path.sep).join('/');
+  if (manifest.files[normalized]) return manifest.files[normalized];
+
+  const dirEntries = Object.entries(manifest.files).filter(([k]) => k.endsWith('/'));
+  dirEntries.sort((a, b) => b[0].length - a[0].length);
+  for (const [entry, mode] of dirEntries) {
+    if (normalized.startsWith(entry)) return mode;
+  }
+  return defaultMode;
+}
+
+// Walk every file under `dir`, returning relative paths (posix-style). Skips
+// template.json and settings.json at the root — both are template metadata
+// that is read for its specific purpose but never copied to the target.
+export async function walkTemplateFiles(
+  dir: string,
+  opts: { skipRoot?: string[] } = {}
+): Promise<string[]> {
+  const skipRoot = new Set(opts.skipRoot ?? ['template.json', 'settings.json']);
+  const out: string[] = [];
+  async function walk(current: string, prefix: string): Promise<void> {
+    let entries: fs.Dirent[];
+    try {
+      entries = await fsPromises.readdir(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        await walk(path.join(current, entry.name), rel);
+      } else if (entry.isFile()) {
+        if (!prefix && skipRoot.has(entry.name)) continue;
+        out.push(rel);
+      }
+    }
+  }
+  await walk(dir, '');
+  return out;
+}
+
+export type FileAction =
+  | { action: 'write'; relPath: string; reason: 'new' | 'refresh' }
+  | { action: 'skip-unchanged'; relPath: string }
+  | { action: 'skip-diverged'; relPath: string; reason: 'edited' | 'no-recorded-sha' }
+  | { action: 'skip-seed-once'; relPath: string }
+  | { action: 'skip-absent-from-template'; relPath: string };
+
+export interface RefreshPlan {
+  actions: FileAction[];
+  nextInstalled: InstalledFiles;
+}
+
+export interface RefreshOptions {
+  defaultMode: FileMode;
+  firstInstall?: boolean;
+  accept?: boolean;
+}
+
+// Produce the per-file plan + the `installed-files.json` state that would
+// follow from applying it. Does not touch disk — the caller decides whether
+// to execute the plan.
+export async function planRefresh(
+  templateDir: string,
+  targetDir: string,
+  manifest: TemplateManifest | null,
+  installed: InstalledFiles | null,
+  options: RefreshOptions
+): Promise<RefreshPlan> {
+  const templateFiles = await walkTemplateFiles(templateDir);
+  const actions: FileAction[] = [];
+  const nextFiles: Record<string, { sha: string }> = {
+    ...(installed?.files ?? {}),
+  };
+
+  for (const rel of templateFiles) {
+    const mode = getFileMode(rel, manifest, options.defaultMode);
+    const templatePath = path.join(templateDir, rel);
+    const targetPath = path.join(targetDir, rel);
+    const templateHash = sha256(await fsPromises.readFile(templatePath));
+
+    if (options.firstInstall) {
+      actions.push({ action: 'write', relPath: rel, reason: 'new' });
+      nextFiles[rel] = { sha: templateHash };
+      continue;
+    }
+
+    if (mode === 'seed-once') {
+      const diskHash = await fileSha(targetPath);
+      const recorded = installed?.files?.[rel]?.sha;
+      if (diskHash === null && !recorded) {
+        // Never seeded before — safe to drop the initial copy.
+        actions.push({ action: 'write', relPath: rel, reason: 'new' });
+        nextFiles[rel] = { sha: templateHash };
+      } else {
+        // Either present, or previously seeded and then deleted by the user.
+        actions.push({ action: 'skip-seed-once', relPath: rel });
+      }
+      continue;
+    }
+
+    // mode === 'track'
+    const recorded = installed?.files?.[rel]?.sha;
+    const diskHash = await fileSha(targetPath);
+
+    if (diskHash === null) {
+      // File vanished — re-seed it and update the SHA.
+      actions.push({ action: 'write', relPath: rel, reason: 'refresh' });
+      nextFiles[rel] = { sha: templateHash };
+      continue;
+    }
+
+    if (!recorded) {
+      if (options.accept) {
+        actions.push({ action: 'write', relPath: rel, reason: 'refresh' });
+        nextFiles[rel] = { sha: templateHash };
+      } else {
+        actions.push({ action: 'skip-diverged', relPath: rel, reason: 'no-recorded-sha' });
+      }
+      continue;
+    }
+
+    if (diskHash === templateHash) {
+      actions.push({ action: 'skip-unchanged', relPath: rel });
+      nextFiles[rel] = { sha: templateHash };
+      continue;
+    }
+
+    if (diskHash === recorded || options.accept) {
+      actions.push({ action: 'write', relPath: rel, reason: 'refresh' });
+      nextFiles[rel] = { sha: templateHash };
+    } else {
+      actions.push({ action: 'skip-diverged', relPath: rel, reason: 'edited' });
+    }
+  }
+
+  return {
+    actions,
+    nextInstalled: { files: nextFiles },
+  };
+}
+
+export async function applyPlan(
+  templateDir: string,
+  targetDir: string,
+  plan: RefreshPlan
+): Promise<void> {
+  for (const action of plan.actions) {
+    if (action.action !== 'write') continue;
+    const src = path.join(templateDir, action.relPath);
+    const dst = path.join(targetDir, action.relPath);
+    await fsPromises.mkdir(path.dirname(dst), { recursive: true });
+    await fsPromises.copyFile(src, dst);
+  }
+}
+
+export async function readInstalledFiles(filePath: string): Promise<InstalledFiles | null> {
+  try {
+    const raw = await fsPromises.readFile(filePath, 'utf-8');
+    const parsed = InstalledFilesSchema.safeParse(JSON.parse(raw));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeInstalledFiles(filePath: string, data: InstalledFiles): Promise<void> {
+  await fsPromises.mkdir(path.dirname(filePath), { recursive: true });
+  // Atomic write: plain writeFile truncates before writing, so a crash mid-
+  // write drops the SHA state entirely and turns every tracked file into a
+  // `no-recorded-sha` skip on the next refresh. rename(2) on the same
+  // filesystem is atomic — readers always see the old or new content.
+  const tmpPath = `${filePath}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+  await fsPromises.writeFile(tmpPath, JSON.stringify(data, null, 2), 'utf-8');
+  await fsPromises.rename(tmpPath, filePath);
+}
+
+// Return an installed-files slice scoped to keys starting with `prefix + '/'`,
+// with the prefix stripped. Used by skill refresh, which runs a plan per
+// skill against a shared `installed-files.json`.
+export function sliceInstalledUnder(
+  installed: InstalledFiles | null,
+  prefix: string
+): InstalledFiles | null {
+  if (!installed?.files) return null;
+  const p = `${prefix}/`;
+  const filtered: Record<string, { sha: string }> = {};
+  for (const [k, v] of Object.entries(installed.files)) {
+    if (k.startsWith(p)) filtered[k.slice(p.length)] = v;
+  }
+  return { files: filtered };
+}
+
+// Re-key a plan's `actions` and `nextInstalled` entries by prefixing every
+// `relPath`. Used for merging a skill plan (with skill-internal paths) back
+// into the workdir-relative installed-files store.
+export function prefixPlanKeys(plan: RefreshPlan, prefix: string): RefreshPlan {
+  const p = prefix ? `${prefix}/` : '';
+  return {
+    actions: plan.actions.map((a) => ({ ...a, relPath: p + a.relPath })),
+    nextInstalled: {
+      files: Object.fromEntries(
+        Object.entries(plan.nextInstalled.files ?? {}).map(([k, v]) => [p + k, v])
+      ),
+    },
+  };
+}

package/src/shared/utils/shell.ts

@@ -0,0 +1,61 @@
+// Splits a command string into argv the way a POSIX shell would, minus
+// expansions: single-quoted strings are literal, double-quoted strings honor
+// `\"` and `\\`, and an unquoted backslash escapes the next character.
+// Throws when a quote is left open.
+export function parseShellArgs(input: string): string[] {
+  const args: string[] = [];
+  let current = '';
+  let inSingle = false;
+  let inDouble = false;
+  let hasContent = false;
+
+  for (let i = 0; i < input.length; i++) {
+    const ch = input[i];
+    if (inSingle) {
+      if (ch === "'") inSingle = false;
+      else current += ch;
+      continue;
+    }
+    if (inDouble) {
+      if (ch === '"') {
+        inDouble = false;
+      } else if (ch === '\\' && i + 1 < input.length) {
+        const next = input[i + 1];
+        if (next === '"' || next === '\\') {
+          current += next;
+          i++;
+        } else {
+          current += ch;
+        }
+      } else {
+        current += ch;
+      }
+      continue;
+    }
+    if (ch === "'") {
+      inSingle = true;
+      hasContent = true;
+    } else if (ch === '"') {
+      inDouble = true;
+      hasContent = true;
+    } else if (ch === '\\' && i + 1 < input.length) {
+      current += input[i + 1];
+      i++;
+      hasContent = true;
+    } else if (ch === ' ' || ch === '\t') {
+      if (hasContent) {
+        args.push(current);
+        current = '';
+        hasContent = false;
+      }
+    } else {
+      current += ch;
+      hasContent = true;
+    }
+  }
+  if (inSingle || inDouble) {
+    throw new Error('Unterminated quote in command string.');
+  }
+  if (hasContent) args.push(current);
+  return args;
+}

package/src/shared/version.ts

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+let cached: string | null = null;
+
+/**
+ * Read the version from the clawmini package.json. Walks up from the current
+ * module's location until a package.json named "clawmini" is found.
+ */
+export function getClawminiVersion(): string {
+  if (cached !== null) return cached;
+  let dir = path.dirname(fileURLToPath(import.meta.url));
+  while (dir !== path.parse(dir).root) {
+    const pkgPath = path.join(dir, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')) as {
+          name?: string;
+          version?: string;
+        };
+        if (pkg.name === 'clawmini' && typeof pkg.version === 'string') {
+          cached = pkg.version;
+          return cached;
+        }
+      } catch {
+        // try parent
+      }
+    }
+    dir = path.dirname(dir);
+  }
+  cached = 'unknown';
+  return cached;
+}

package/src/shared/workspace.test.ts

@@ -24,8 +24,12 @@ import {
   readEnvironment,
   getActiveEnvironmentName,
   resolveTargetAgentSkillsDir,
+  resolvePolicies,
+  readEnvironmentPoliciesForPath,
+  readPoliciesForPath,
 } from './workspace.js';
 import type { Agent, Settings, Environment } from './config.js';
+import { BUILTIN_POLICIES } from './policies.js';
 
 describe('workspace utilities', () => {
   const testDir = path.join(process.cwd(), '.clawmini-test-workspace');
@@ -189,6 +193,49 @@ describe('workspace utilities', () => {
       list = await listAgents(testDir);
       expect(list).not.toContain('agent-to-delete');
     });
+
+    it('should serialize concurrent updateAgentOverlay calls', async () => {
+      const { updateAgentOverlay, agentSettingsLocks } = await import('./workspace.js');
+      await writeAgentSettings('lock-agent', { env: { COUNT: '0' } }, testDir);
+
+      // Fire many concurrent increments. Without the lock, the read-modify-write
+      // races and the final count is < N.
+      const N = 20;
+      await Promise.all(
+        Array.from({ length: N }, () =>
+          updateAgentOverlay(
+            'lock-agent',
+            (overlay) => {
+              const prev = Number((overlay.env?.COUNT as string) ?? '0');
+              return { ...overlay, env: { ...(overlay.env ?? {}), COUNT: String(prev + 1) } };
+            },
+            testDir
+          )
+        )
+      );
+
+      const final = await getAgent('lock-agent', testDir);
+      expect(final?.env?.COUNT).toBe(String(N));
+      expect(agentSettingsLocks.size).toBe(0);
+    });
+
+    it('should throw from updateAgentOverlay when the overlay is missing', async () => {
+      const { updateAgentOverlay } = await import('./workspace.js');
+      await expect(
+        updateAgentOverlay('ghost-agent', (overlay) => overlay, testDir)
+      ).rejects.toThrow(/no settings overlay/);
+    });
+
+    it('should skip the write when updateAgentOverlay updater returns null', async () => {
+      const { updateAgentOverlay } = await import('./workspace.js');
+      await writeAgentSettings('skip-agent', { env: { KEEP: '1' } }, testDir);
+
+      const wrote = await updateAgentOverlay('skip-agent', () => null, testDir);
+      expect(wrote).toBe(false);
+
+      const after = await getAgent('skip-agent', testDir);
+      expect(after?.env?.KEEP).toBe('1');
+    });
   });
 
   describe('resolveTargetAgentSkillsDir', () => {
@@ -386,4 +433,174 @@ describe('workspace utilities', () => {
       expect(await getActiveEnvironmentName('./', testDir)).toBeNull();
     });
   });
+
+  describe('resolvePolicies', () => {
+    const scriptsDir = path.join(clawminiDir, 'policy-scripts');
+    const proposeScript = path.join(scriptsDir, 'manage-policies.js');
+
+    function installProposePolicyScript() {
+      fs.mkdirSync(scriptsDir, { recursive: true });
+      fs.writeFileSync(proposeScript, '#!/usr/bin/env node\n');
+    }
+
+    it('returns null when the file is null', () => {
+      expect(resolvePolicies(null, clawminiDir)).toBeNull();
+    });
+
+    it('injects manage-policies when its script is installed', () => {
+      installProposePolicyScript();
+      const resolved = resolvePolicies({ policies: {} }, clawminiDir);
+      expect(resolved?.policies['manage-policies']).toEqual({
+        ...BUILTIN_POLICIES['manage-policies'],
+        command: proposeScript,
+      });
+    });
+
+    it('resolves relative command paths against the workspace root', () => {
+      const resolved = resolvePolicies(
+        {
+          policies: {
+            local: { command: './scripts/tool.sh' },
+            parent: { command: '../outside/tool.sh' },
+            absolute: { command: '/usr/bin/env' },
+            bare: { command: 'echo' },
+          },
+        },
+        clawminiDir
+      );
+      const workspaceRoot = path.dirname(clawminiDir);
+      expect(resolved?.policies.local?.command).toBe(
+        path.resolve(workspaceRoot, 'scripts/tool.sh')
+      );
+      expect(resolved?.policies.parent?.command).toBe(
+        path.resolve(workspaceRoot, '../outside/tool.sh')
+      );
+      expect(resolved?.policies.absolute?.command).toBe('/usr/bin/env');
+      expect(resolved?.policies.bare?.command).toBe('echo');
+    });
+
+    it('omits manage-policies when its script is missing', () => {
+      const resolved = resolvePolicies({ policies: {} }, clawminiDir);
+      expect(resolved?.policies['manage-policies']).toBeUndefined();
+    });
+
+    it('omits manage-policies when explicitly disabled, even if script exists', () => {
+      installProposePolicyScript();
+      const resolved = resolvePolicies({ policies: { 'manage-policies': false } }, clawminiDir);
+      expect(resolved?.policies['manage-policies']).toBeUndefined();
+    });
+
+    it('preserves a user-defined manage-policies without overwriting', () => {
+      installProposePolicyScript();
+      const custom = { command: 'echo', args: ['custom'], description: 'mine' };
+      const resolved = resolvePolicies({ policies: { 'manage-policies': custom } }, clawminiDir);
+      expect(resolved?.policies['manage-policies']).toEqual(custom);
+    });
+
+    it('strips arbitrary entries set to false', () => {
+      const resolved = resolvePolicies(
+        {
+          policies: {
+            keep: { command: 'ls' },
+            drop: false,
+          },
+        },
+        clawminiDir
+      );
+      expect(resolved?.policies.keep).toEqual({ command: 'ls' });
+      expect(resolved?.policies.drop).toBeUndefined();
+    });
+
+    it('does not mutate its input', () => {
+      installProposePolicyScript();
+      const file = { policies: { drop: false as const, keep: { command: 'ls' } } };
+      const before = JSON.parse(JSON.stringify(file));
+      resolvePolicies(file, clawminiDir);
+      expect(file).toEqual(before);
+    });
+  });
+
+  describe('environment-scoped policies', () => {
+    async function writeEnvWithPolicies(
+      envName: string,
+      policies: Record<string, unknown>
+    ): Promise<string> {
+      const envDir = path.join(clawminiDir, 'environments', envName);
+      await fsPromises.mkdir(envDir, { recursive: true });
+      await fsPromises.writeFile(
+        path.join(envDir, 'env.json'),
+        JSON.stringify({ policies }),
+        'utf-8'
+      );
+      return envDir;
+    }
+
+    it('returns empty when there is no active environment', async () => {
+      const result = await readEnvironmentPoliciesForPath('./', testDir);
+      expect(result).toEqual({});
+    });
+
+    it('returns empty when the active env has no policies field', async () => {
+      const envDir = path.join(clawminiDir, 'environments', 'bare');
+      await fsPromises.mkdir(envDir, { recursive: true });
+      await fsPromises.writeFile(path.join(envDir, 'env.json'), JSON.stringify({}), 'utf-8');
+      await writeSettings({ environments: { './': 'bare' } }, testDir);
+      const result = await readEnvironmentPoliciesForPath('./', testDir);
+      expect(result).toEqual({});
+    });
+
+    it('resolves relative commands against the env directory', async () => {
+      const envDir = await writeEnvWithPolicies('sandbox-env', {
+        'allowlist-domain': {
+          description: 'Adds a domain',
+          command: './allowlist-domain.mjs',
+          allowHelp: false,
+        },
+      });
+      await writeSettings({ environments: { './': 'sandbox-env' } }, testDir);
+
+      const result = await readEnvironmentPoliciesForPath('./', testDir);
+      expect(result['allowlist-domain']?.command).toBe(path.join(envDir, 'allowlist-domain.mjs'));
+      expect(result['allowlist-domain']?.description).toBe('Adds a domain');
+    });
+
+    it('leaves non-relative commands untouched', async () => {
+      await writeEnvWithPolicies('cmd-env', {
+        echo: { command: 'echo' },
+      });
+      await writeSettings({ environments: { './': 'cmd-env' } }, testDir);
+
+      const result = await readEnvironmentPoliciesForPath('./', testDir);
+      expect(result.echo?.command).toBe('echo');
+    });
+
+    it('hides env policies when the target is outside the env subpath', async () => {
+      await writeEnvWithPolicies('scoped-env', {
+        'only-here': { command: './cmd.js' },
+      });
+      await writeSettings({ environments: { './agents/scoped': 'scoped-env' } }, testDir);
+
+      expect(await readEnvironmentPoliciesForPath('./', testDir)).toEqual({});
+      expect(await readEnvironmentPoliciesForPath('./other', testDir)).toEqual({});
+
+      const scopedResult = await readEnvironmentPoliciesForPath('./agents/scoped', testDir);
+      expect(scopedResult['only-here']).toBeDefined();
+    });
+
+    it('merges env policies on top of global ones via readPoliciesForPath', async () => {
+      await fsPromises.mkdir(path.join(clawminiDir, 'policy-scripts'), { recursive: true });
+      await fsPromises.writeFile(
+        path.join(clawminiDir, 'policies.json'),
+        JSON.stringify({ policies: { global: { command: 'globalcmd' } } }),
+        'utf-8'
+      );
+      await writeEnvWithPolicies('merge-env', {
+        'env-only': { command: './env.js' },
+      });
+      await writeSettings({ environments: { './': 'merge-env' } }, testDir);
+
+      const result = await readPoliciesForPath('./', testDir);
+      expect(Object.keys(result?.policies || {}).sort()).toEqual(['env-only', 'global']);
+    });
+  });
 });