devflow-kit 0.8.1 → 1.0.0

package/dist/utils/post-install.js

@@ -0,0 +1,427 @@
+import { promises as fs, writeFileSync, unlinkSync } from 'fs';
+import { execSync } from 'child_process';
+import * as path from 'path';
+import * as p from '@clack/prompts';
+import { getManagedSettingsPath } from './paths.js';
+function isNodeSystemError(error) {
+    return (error instanceof Error &&
+        'code' in error &&
+        typeof error.code === 'string');
+}
+/**
+ * Replace ${DEVFLOW_DIR} placeholders in a settings template.
+ */
+export function substituteSettingsTemplate(template, devflowDir) {
+    return template.replace(/\$\{DEVFLOW_DIR\}/g, devflowDir);
+}
+/**
+ * Add Agent Teams configuration to settings JSON.
+ * Sets teammateMode and CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS env var.
+ */
+export function applyTeamsConfig(settingsJson) {
+    const settings = JSON.parse(settingsJson);
+    settings.teammateMode = 'auto';
+    if (!settings.env) {
+        settings.env = {};
+    }
+    settings.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = '1';
+    return JSON.stringify(settings, null, 2) + '\n';
+}
+/**
+ * Remove Agent Teams configuration from settings JSON.
+ * Strips teammateMode and CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS env var.
+ */
+export function stripTeamsConfig(settingsJson) {
+    const settings = JSON.parse(settingsJson);
+    delete settings.teammateMode;
+    if (settings.env) {
+        delete settings.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
+        if (Object.keys(settings.env).length === 0) {
+            delete settings.env;
+        }
+    }
+    return JSON.stringify(settings, null, 2) + '\n';
+}
+/**
+ * Compute which entries need appending to a .gitignore file.
+ * Returns only entries not already present.
+ */
+export function computeGitignoreAppend(existingContent, entries) {
+    const existingLines = existingContent.split('\n').map(l => l.trim());
+    return entries.filter(entry => !existingLines.includes(entry));
+}
+/**
+ * Merge DevFlow deny entries into an existing managed settings object.
+ * Preserves existing entries, deduplicates, and returns the merged JSON string.
+ */
+export function mergeDenyList(existingJson, newDenyEntries) {
+    const existing = JSON.parse(existingJson);
+    const currentDeny = existing.permissions?.deny ?? [];
+    const merged = [...new Set([...currentDeny, ...newDenyEntries])];
+    existing.permissions = { ...existing.permissions, deny: merged };
+    return JSON.stringify(existing, null, 2) + '\n';
+}
+/**
+ * Attempt to install managed settings (security deny list) to the system path.
+ * Managed settings have highest precedence in Claude Code and cannot be overridden.
+ *
+ * Strategy:
+ * 1. Try direct write (works if running as root or directory is writable)
+ * 2. If EACCES in TTY, offer to retry with sudo
+ * 3. Returns true if managed settings were written, false if caller should fall back
+ */
+export async function installManagedSettings(rootDir, verbose) {
+    let managedPath;
+    try {
+        managedPath = getManagedSettingsPath();
+    }
+    catch {
+        return false; // Unsupported platform
+    }
+    const managedDir = path.dirname(managedPath);
+    const sourceManaged = path.join(rootDir, 'src', 'templates', 'managed-settings.json');
+    let newDenyEntries;
+    try {
+        const template = JSON.parse(await fs.readFile(sourceManaged, 'utf-8'));
+        newDenyEntries = template.permissions?.deny ?? [];
+    }
+    catch {
+        if (verbose) {
+            p.log.warn('Could not read managed settings template');
+        }
+        return false;
+    }
+    // Build the content to write (merge with existing if present)
+    let content;
+    try {
+        const existing = await fs.readFile(managedPath, 'utf-8');
+        content = mergeDenyList(existing, newDenyEntries);
+    }
+    catch {
+        // File doesn't exist — use template as-is
+        content = JSON.stringify({ permissions: { deny: newDenyEntries } }, null, 2) + '\n';
+    }
+    // Attempt 1: direct write
+    try {
+        await fs.mkdir(managedDir, { recursive: true });
+        await fs.writeFile(managedPath, content, 'utf-8');
+        if (verbose) {
+            p.log.success(`Managed settings written to ${managedPath}`);
+        }
+        return true;
+    }
+    catch (error) {
+        if (!isNodeSystemError(error) || error.code !== 'EACCES') {
+            if (verbose) {
+                p.log.warn(`Could not write managed settings: ${error}`);
+            }
+            return false;
+        }
+    }
+    // Attempt 2: sudo (TTY only)
+    if (!process.stdin.isTTY) {
+        return false;
+    }
+    const confirmed = await p.confirm({
+        message: `Managed settings require admin access (${managedDir}). Use sudo?`,
+        initialValue: true,
+    });
+    if (p.isCancel(confirmed) || !confirmed) {
+        return false;
+    }
+    try {
+        execSync(`sudo mkdir -p '${managedDir}'`, { stdio: 'inherit' });
+        // Write via sudo tee to avoid shell quoting issues with the JSON content
+        const tmpFile = path.join(rootDir, '.managed-settings-tmp.json');
+        await fs.writeFile(tmpFile, content, 'utf-8');
+        execSync(`sudo cp '${tmpFile}' '${managedPath}'`, { stdio: 'inherit' });
+        await fs.rm(tmpFile, { force: true });
+        if (verbose) {
+            p.log.success(`Managed settings written to ${managedPath} (via sudo)`);
+        }
+        return true;
+    }
+    catch (error) {
+        if (verbose) {
+            p.log.warn(`sudo write failed: ${error}`);
+        }
+        return false;
+    }
+}
+/**
+ * Remove DevFlow deny entries from managed settings.
+ * If only DevFlow entries remain, deletes the file entirely.
+ *
+ * Mirrors installManagedSettings strategy:
+ * 1. Try direct write/delete
+ * 2. If EACCES and TTY, ask user before sudo
+ * 3. Non-TTY: return false (caller logs preservation message)
+ */
+export async function removeManagedSettings(rootDir, verbose) {
+    let managedPath;
+    try {
+        managedPath = getManagedSettingsPath();
+    }
+    catch {
+        return false;
+    }
+    let existingContent;
+    try {
+        existingContent = await fs.readFile(managedPath, 'utf-8');
+    }
+    catch {
+        return false; // File doesn't exist
+    }
+    // Load our deny entries to identify which to remove
+    const sourceManaged = path.join(rootDir, 'src', 'templates', 'managed-settings.json');
+    let devflowDenyEntries;
+    try {
+        const template = JSON.parse(await fs.readFile(sourceManaged, 'utf-8'));
+        devflowDenyEntries = template.permissions?.deny ?? [];
+    }
+    catch {
+        return false;
+    }
+    const existing = JSON.parse(existingContent);
+    const currentDeny = existing.permissions?.deny ?? [];
+    const devflowSet = new Set(devflowDenyEntries);
+    const remaining = currentDeny.filter(entry => !devflowSet.has(entry));
+    // Determine the target action: delete file entirely or write updated content
+    let shouldDelete = false;
+    let updatedContent = null;
+    if (remaining.length === 0) {
+        const otherKeys = Object.keys(existing).filter(k => k !== 'permissions');
+        const hasOtherPermissions = existing.permissions &&
+            Object.keys(existing.permissions).filter(k => k !== 'deny').length > 0;
+        if (otherKeys.length === 0 && !hasOtherPermissions) {
+            shouldDelete = true;
+        }
+        else {
+            delete existing.permissions.deny;
+            if (Object.keys(existing.permissions).length === 0) {
+                delete existing.permissions;
+            }
+            updatedContent = JSON.stringify(existing, null, 2) + '\n';
+        }
+    }
+    else {
+        existing.permissions.deny = remaining;
+        updatedContent = JSON.stringify(existing, null, 2) + '\n';
+    }
+    // Attempt 1: direct write/delete
+    try {
+        if (shouldDelete) {
+            unlinkSync(managedPath);
+        }
+        else {
+            writeFileSync(managedPath, updatedContent, 'utf-8');
+        }
+        if (verbose) {
+            p.log.success(shouldDelete ? 'Managed settings file removed' : 'DevFlow deny entries removed from managed settings');
+        }
+        return true;
+    }
+    catch (error) {
+        if (!isNodeSystemError(error) || error.code !== 'EACCES') {
+            if (verbose) {
+                p.log.warn(`Could not update managed settings: ${error}`);
+            }
+            return false;
+        }
+    }
+    // Attempt 2: sudo (TTY only, with explicit consent)
+    if (!process.stdin.isTTY) {
+        return false;
+    }
+    const managedDir = path.dirname(managedPath);
+    const confirmed = await p.confirm({
+        message: `Managed settings cleanup requires admin access (${managedDir}). Use sudo?`,
+        initialValue: true,
+    });
+    if (p.isCancel(confirmed) || !confirmed) {
+        return false;
+    }
+    try {
+        if (shouldDelete) {
+            execSync(`sudo rm '${managedPath}'`, { stdio: 'inherit' });
+        }
+        else {
+            const tmpFile = path.join(rootDir, '.managed-settings-tmp.json');
+            await fs.writeFile(tmpFile, updatedContent, 'utf-8');
+            execSync(`sudo cp '${tmpFile}' '${managedPath}'`, { stdio: 'inherit' });
+            await fs.rm(tmpFile, { force: true });
+        }
+        if (verbose) {
+            p.log.success(shouldDelete ? 'Managed settings file removed' : 'DevFlow deny entries removed from managed settings');
+        }
+        return true;
+    }
+    catch (error) {
+        if (verbose) {
+            p.log.warn(`sudo cleanup failed: ${error}`);
+        }
+        return false;
+    }
+}
+/**
+ * Install or update settings.json with DevFlow configuration.
+ * Prompts interactively in TTY mode when settings already exist.
+ * In non-TTY mode, skips override (safe default).
+ *
+ * When securityMode is 'managed', the deny list goes to system-level managed
+ * settings and is excluded from user settings.json. When 'user', the deny list
+ * is included in settings.json (original behavior).
+ */
+export async function installSettings(claudeDir, rootDir, devflowDir, verbose, teamsEnabled = false, securityMode = 'user') {
+    const settingsPath = path.join(claudeDir, 'settings.json');
+    const sourceSettingsPath = path.join(rootDir, 'src', 'templates', 'settings.json');
+    try {
+        const settingsTemplate = await fs.readFile(sourceSettingsPath, 'utf-8');
+        let settingsContent = substituteSettingsTemplate(settingsTemplate, devflowDir);
+        // When securityMode is 'user', inject deny list from managed-settings template
+        if (securityMode === 'user') {
+            const managedTemplatePath = path.join(rootDir, 'src', 'templates', 'managed-settings.json');
+            try {
+                const managedTemplate = JSON.parse(await fs.readFile(managedTemplatePath, 'utf-8'));
+                const settings = JSON.parse(settingsContent);
+                settings.permissions = managedTemplate.permissions;
+                settingsContent = JSON.stringify(settings, null, 2) + '\n';
+            }
+            catch {
+                if (verbose) {
+                    p.log.warn('Could not load security deny list — settings will be written without it');
+                }
+            }
+        }
+        if (!teamsEnabled) {
+            settingsContent = stripTeamsConfig(settingsContent);
+        }
+        let settingsExists = false;
+        try {
+            await fs.access(settingsPath);
+            settingsExists = true;
+        }
+        catch {
+            settingsExists = false;
+        }
+        if (!settingsExists) {
+            await fs.writeFile(settingsPath, settingsContent, 'utf-8');
+            if (verbose) {
+                p.log.success('Settings configured');
+            }
+            return;
+        }
+        // Settings exist — check if they already have hooks
+        let hasHooks = false;
+        try {
+            const existing = JSON.parse(await fs.readFile(settingsPath, 'utf-8'));
+            hasHooks = !!existing.hooks;
+        }
+        catch { /* parse error = treat as no hooks */ }
+        if (hasHooks) {
+            const existing = await fs.readFile(settingsPath, 'utf-8');
+            const updated = teamsEnabled
+                ? applyTeamsConfig(existing)
+                : stripTeamsConfig(existing);
+            await fs.writeFile(settingsPath, updated, 'utf-8');
+            if (verbose) {
+                p.log.info(`Settings updated (teams ${teamsEnabled ? 'enabled' : 'disabled'})`);
+            }
+            return;
+        }
+        // Settings exist without hooks — prompt in TTY, warn in non-TTY
+        if (process.stdin.isTTY) {
+            const confirmed = await p.confirm({
+                message: 'settings.json exists without hooks (Working Memory needs hooks). Override?',
+                initialValue: true,
+            });
+            if (p.isCancel(confirmed)) {
+                p.cancel('Installation cancelled.');
+                process.exit(0);
+            }
+            if (confirmed) {
+                await fs.writeFile(settingsPath, settingsContent, 'utf-8');
+                p.log.success('Settings overridden');
+            }
+            else {
+                p.log.info('Keeping existing settings');
+            }
+        }
+        else {
+            p.log.warn('Settings exist without hooks. Working Memory requires hooks.');
+            p.log.info('Re-run interactively to configure, or manually add hooks to settings.json');
+        }
+    }
+    catch (error) {
+        if (verbose) {
+            p.log.warn(`Could not configure settings: ${error}`);
+        }
+    }
+}
+/**
+ * Create .claudeignore in git repository root (skip if already exists).
+ */
+export async function installClaudeignore(gitRoot, rootDir, verbose) {
+    const claudeignorePath = path.join(gitRoot, '.claudeignore');
+    const claudeignoreTemplatePath = path.join(rootDir, 'src', 'templates', 'claudeignore.template');
+    try {
+        const claudeignoreContent = await fs.readFile(claudeignoreTemplatePath, 'utf-8');
+        await fs.writeFile(claudeignorePath, claudeignoreContent, { encoding: 'utf-8', flag: 'wx' });
+        if (verbose) {
+            p.log.success('.claudeignore created');
+        }
+    }
+    catch (error) {
+        if (isNodeSystemError(error) && error.code === 'EEXIST') {
+            // Already exists, skip silently
+        }
+        else if (verbose) {
+            p.log.warn(`Could not create .claudeignore: ${error}`);
+        }
+    }
+}
+/**
+ * Update .gitignore with DevFlow entries (for local scope installs).
+ */
+export async function updateGitignore(gitRoot, verbose) {
+    try {
+        const gitignorePath = path.join(gitRoot, '.gitignore');
+        const entriesToAdd = ['.claude/', '.devflow/'];
+        let gitignoreContent = '';
+        try {
+            gitignoreContent = await fs.readFile(gitignorePath, 'utf-8');
+        }
+        catch { /* doesn't exist */ }
+        const linesToAdd = computeGitignoreAppend(gitignoreContent, entriesToAdd);
+        if (linesToAdd.length > 0) {
+            const newContent = gitignoreContent
+                ? `${gitignoreContent.trimEnd()}\n\n# DevFlow local installation\n${linesToAdd.join('\n')}\n`
+                : `# DevFlow local installation\n${linesToAdd.join('\n')}\n`;
+            await fs.writeFile(gitignorePath, newContent, 'utf-8');
+            if (verbose) {
+                p.log.success('.gitignore updated');
+            }
+        }
+    }
+    catch (error) {
+        if (verbose) {
+            p.log.warn(`Could not update .gitignore: ${error instanceof Error ? error.message : error}`);
+        }
+    }
+}
+/**
+ * Create .docs/ directory structure for DevFlow artifacts.
+ */
+export async function createDocsStructure(verbose) {
+    const docsDir = path.join(process.cwd(), '.docs');
+    try {
+        await fs.mkdir(path.join(docsDir, 'status', 'compact'), { recursive: true });
+        await fs.mkdir(path.join(docsDir, 'reviews'), { recursive: true });
+        await fs.mkdir(path.join(docsDir, 'releases'), { recursive: true });
+        if (verbose) {
+            p.log.success('.docs/ structure ready');
+        }
+    }
+    catch { /* may already exist */ }
+}
+//# sourceMappingURL=post-install.js.map

package/dist/utils/safe-delete-install.d.ts

@@ -0,0 +1,22 @@
+import type { Shell } from './safe-delete.js';
+/**
+ * Generate the safe-delete shell function block with markers.
+ * Returns null for unsupported shells.
+ */
+export declare function generateSafeDeleteBlock(shell: Shell, platform: NodeJS.Platform, trashCommand: string | null): string | null;
+/**
+ * Check if the safe-delete block is already installed in a profile file.
+ */
+export declare function isAlreadyInstalled(profilePath: string): Promise<boolean>;
+/**
+ * Append the safe-delete block to a profile file.
+ * Creates parent directories and the file if they don't exist.
+ */
+export declare function installToProfile(profilePath: string, block: string): Promise<void>;
+/**
+ * Remove the safe-delete block from a profile file.
+ * Returns true if the block was found and removed, false otherwise.
+ * For fish function files, deletes the file if it becomes empty.
+ */
+export declare function removeFromProfile(profilePath: string): Promise<boolean>;
+//# sourceMappingURL=safe-delete-install.d.ts.map

package/dist/utils/safe-delete-install.js

@@ -0,0 +1,156 @@
+import { promises as fs } from 'fs';
+import * as path from 'path';
+const START_MARKER = '# >>> DevFlow safe-delete >>>';
+const END_MARKER = '# <<< DevFlow safe-delete <<<';
+/**
+ * Generate the safe-delete shell function block with markers.
+ * Returns null for unsupported shells.
+ */
+export function generateSafeDeleteBlock(shell, platform, trashCommand) {
+    if (shell === 'unknown')
+        return null;
+    if (shell === 'bash' || shell === 'zsh') {
+        const cmd = trashCommand ?? 'trash';
+        return [
+            START_MARKER,
+            `rm() {`,
+            `  local files=()`,
+            `  for arg in "$@"; do`,
+            `    [[ "$arg" =~ ^- ]] || files+=("$arg")`,
+            `  done`,
+            `  if (( \${#files[@]} > 0 )); then`,
+            `    ${cmd} "\${files[@]}"`,
+            `  fi`,
+            `}`,
+            `command() {`,
+            `  if [[ "$1" == "rm" ]]; then`,
+            `    shift; rm "$@"`,
+            `  else`,
+            `    builtin command "$@"`,
+            `  fi`,
+            `}`,
+            END_MARKER,
+        ].join('\n');
+    }
+    if (shell === 'fish') {
+        const cmd = trashCommand ?? 'trash';
+        return [
+            START_MARKER,
+            `function rm --description "Safe delete via trash"`,
+            `  set -l files`,
+            `  for arg in $argv`,
+            `    if not string match -q -- '-*' $arg`,
+            `      set files $files $arg`,
+            `    end`,
+            `  end`,
+            `  if test (count $files) -gt 0`,
+            `    ${cmd} $files`,
+            `  end`,
+            `end`,
+            END_MARKER,
+        ].join('\n');
+    }
+    if (shell === 'powershell') {
+        if (platform === 'win32') {
+            return [
+                START_MARKER,
+                `if (Get-Alias rm -ErrorAction SilentlyContinue) {`,
+                `  Remove-Alias rm -Force -Scope Global`,
+                `}`,
+                `function rm {`,
+                `  $files = $args | Where-Object { $_ -notlike '-*' }`,
+                `  if ($files) {`,
+                `    Add-Type -AssemblyName Microsoft.VisualBasic`,
+                `    foreach ($f in $files) {`,
+                `      $p = Resolve-Path $f -ErrorAction SilentlyContinue`,
+                `      if ($p) {`,
+                `        if (Test-Path $p -PathType Container) {`,
+                `          [Microsoft.VisualBasic.FileIO.FileSystem]::DeleteDirectory(`,
+                `            $p, 'OnlyErrorDialogs', 'SendToRecycleBin')`,
+                `        } else {`,
+                `          [Microsoft.VisualBasic.FileIO.FileSystem]::DeleteFile(`,
+                `            $p, 'OnlyErrorDialogs', 'SendToRecycleBin')`,
+                `        }`,
+                `      }`,
+                `    }`,
+                `  }`,
+                `}`,
+                END_MARKER,
+            ].join('\n');
+        }
+        // macOS/Linux PowerShell
+        const cmd = trashCommand ?? 'trash';
+        return [
+            START_MARKER,
+            `if (Get-Alias rm -ErrorAction SilentlyContinue) {`,
+            `  Remove-Alias rm -Force -Scope Global`,
+            `}`,
+            `function rm {`,
+            `  $files = $args | Where-Object { $_ -notlike '-*' }`,
+            `  if ($files) { & ${cmd} @files }`,
+            `}`,
+            END_MARKER,
+        ].join('\n');
+    }
+    return null;
+}
+/**
+ * Check if the safe-delete block is already installed in a profile file.
+ */
+export async function isAlreadyInstalled(profilePath) {
+    try {
+        const content = await fs.readFile(profilePath, 'utf-8');
+        return content.includes(START_MARKER) && content.includes(END_MARKER);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Append the safe-delete block to a profile file.
+ * Creates parent directories and the file if they don't exist.
+ */
+export async function installToProfile(profilePath, block) {
+    await fs.mkdir(path.dirname(profilePath), { recursive: true });
+    let existing = '';
+    try {
+        existing = await fs.readFile(profilePath, 'utf-8');
+    }
+    catch {
+        // File doesn't exist yet — will be created
+    }
+    const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n\n' : '\n';
+    const content = existing.length > 0 ? existing + separator + block + '\n' : block + '\n';
+    await fs.writeFile(profilePath, content, 'utf-8');
+}
+/**
+ * Remove the safe-delete block from a profile file.
+ * Returns true if the block was found and removed, false otherwise.
+ * For fish function files, deletes the file if it becomes empty.
+ */
+export async function removeFromProfile(profilePath) {
+    let content;
+    try {
+        content = await fs.readFile(profilePath, 'utf-8');
+    }
+    catch {
+        return false;
+    }
+    const startIdx = content.indexOf(START_MARKER);
+    const endIdx = content.indexOf(END_MARKER);
+    if (startIdx === -1 || endIdx === -1)
+        return false;
+    const before = content.slice(0, startIdx);
+    const after = content.slice(endIdx + END_MARKER.length);
+    // Clean up surrounding whitespace
+    const cleaned = (before.trimEnd() + after.trimStart()).trim();
+    if (cleaned.length === 0) {
+        // File is empty after removal — delete it (fish function files)
+        await fs.unlink(profilePath);
+    }
+    else {
+        await fs.writeFile(profilePath, cleaned + '\n', 'utf-8');
+    }
+    return true;
+}
+//# sourceMappingURL=safe-delete-install.js.map

package/dist/utils/safe-delete.d.ts

@@ -0,0 +1,12 @@
+export type Platform = 'macos' | 'linux' | 'windows';
+export type Shell = 'zsh' | 'bash' | 'fish' | 'powershell' | 'unknown';
+export interface SafeDeleteInfo {
+    command: string | null;
+    installHint: string | null;
+}
+export declare function detectPlatform(): Platform;
+export declare function detectShell(): Shell;
+export declare function getProfilePath(shell: Shell): string | null;
+export declare function getSafeDeleteInfo(platform: Platform): SafeDeleteInfo;
+export declare function hasSafeDelete(platform: Platform): boolean;
+//# sourceMappingURL=safe-delete.d.ts.map