@shepai/cli 1.14.2 → 1.15.1

package/dist/src/infrastructure/services/external/github-issue.service.js

@@ -0,0 +1,59 @@
+/**
+ * GitHub Issue Fetcher Service
+ *
+ * Fetches GitHub issues using the gh CLI subprocess.
+ * Supports owner/repo#number and #number (current repo) formats.
+ */
+import { IssueNotFoundError, IssueServiceUnavailableError, } from '../../../application/ports/output/services/external-issue-fetcher.interface.js';
+export class GitHubIssueFetcher {
+    execFile;
+    constructor(execFile) {
+        this.execFile = execFile;
+    }
+    async fetchGitHubIssue(ref) {
+        const { issueNumber, repo } = this.parseRef(ref);
+        const args = ['issue', 'view', issueNumber];
+        if (repo) {
+            args.push('--repo', repo);
+        }
+        args.push('--json', 'title,body,labels,url');
+        try {
+            const { stdout } = await this.execFile('gh', args, { timeout: 30_000 });
+            const data = JSON.parse(stdout);
+            return {
+                title: data.title,
+                description: data.body ?? '',
+                labels: data.labels.map((l) => l.name),
+                url: data.url,
+                source: 'github',
+            };
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            if (error.code === 'ENOENT') {
+                throw new IssueServiceUnavailableError('GitHub CLI (gh) is not installed. Install it from https://cli.github.com/');
+            }
+            if (error.message.includes('Could not resolve')) {
+                throw new IssueNotFoundError(`GitHub issue ${ref} not found`);
+            }
+            throw new IssueNotFoundError(`Failed to fetch GitHub issue ${ref}: ${error.message}`);
+        }
+    }
+    parseRef(ref) {
+        // Format: owner/repo#123
+        const fullMatch = ref.match(/^([^#]+)#(\d+)$/);
+        if (fullMatch) {
+            return { issueNumber: fullMatch[2], repo: fullMatch[1] };
+        }
+        // Format: #123
+        const hashMatch = ref.match(/^#(\d+)$/);
+        if (hashMatch) {
+            return { issueNumber: hashMatch[1] };
+        }
+        // Format: plain number
+        if (/^\d+$/.test(ref)) {
+            return { issueNumber: ref };
+        }
+        throw new IssueNotFoundError(`Invalid GitHub issue reference: ${ref}`);
+    }
+}

package/dist/src/infrastructure/services/external/jira-ticket.service.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Jira Ticket Fetcher Service
+ *
+ * Fetches Jira tickets using the Jira REST API v3 via fetch.
+ * Requires baseUrl, email, and API token for authentication.
+ */
+import type { IExternalIssueFetcher, ExternalIssue } from '../../../application/ports/output/services/external-issue-fetcher.interface.js';
+type FetchFn = (url: string, init?: RequestInit) => Promise<Response>;
+export interface JiraConfig {
+    baseUrl: string;
+    email: string;
+    token: string;
+    fetchFn?: FetchFn;
+}
+export declare class JiraTicketFetcher implements Pick<IExternalIssueFetcher, 'fetchJiraTicket'> {
+    private readonly baseUrl;
+    private readonly authHeader;
+    private readonly fetchFn;
+    constructor(config: JiraConfig);
+    fetchJiraTicket(key: string): Promise<ExternalIssue>;
+}
+export {};
+//# sourceMappingURL=jira-ticket.service.d.ts.map

package/dist/src/infrastructure/services/external/jira-ticket.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jira-ticket.service.d.ts","sourceRoot":"","sources":["../../../../../src/infrastructure/services/external/jira-ticket.service.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,qBAAqB,EACrB,aAAa,EACd,MAAM,yEAAyE,CAAC;AAOjF,KAAK,OAAO,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEtE,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,iBAAkB,YAAW,IAAI,CAAC,qBAAqB,EAAE,iBAAiB,CAAC;IACtF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;gBAEtB,MAAM,EAAE,UAAU;IAYxB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;CAqD3D"}

package/dist/src/infrastructure/services/external/jira-ticket.service.js

@@ -0,0 +1,57 @@
+/**
+ * Jira Ticket Fetcher Service
+ *
+ * Fetches Jira tickets using the Jira REST API v3 via fetch.
+ * Requires baseUrl, email, and API token for authentication.
+ */
+import { IssueNotFoundError, IssueAuthenticationError, IssueServiceUnavailableError, } from '../../../application/ports/output/services/external-issue-fetcher.interface.js';
+export class JiraTicketFetcher {
+    baseUrl;
+    authHeader;
+    fetchFn;
+    constructor(config) {
+        if (!config.baseUrl) {
+            throw new IssueServiceUnavailableError('Jira configuration is incomplete: baseUrl is required');
+        }
+        this.baseUrl = config.baseUrl.replace(/\/$/, '');
+        this.authHeader = `Basic ${Buffer.from(`${config.email}:${config.token}`).toString('base64')}`;
+        this.fetchFn = config.fetchFn ?? globalThis.fetch;
+    }
+    async fetchJiraTicket(key) {
+        const url = `${this.baseUrl}/rest/api/3/issue/${key}?fields=summary,description,labels`;
+        try {
+            const response = await this.fetchFn(url, {
+                headers: {
+                    Authorization: this.authHeader,
+                    Accept: 'application/json',
+                },
+            });
+            if (!response.ok) {
+                if (response.status === 404) {
+                    throw new IssueNotFoundError(`Jira ticket ${key} not found`);
+                }
+                if (response.status === 401 || response.status === 403) {
+                    throw new IssueAuthenticationError(`Jira authentication failed (${response.status}): check your email and API token`);
+                }
+                throw new IssueServiceUnavailableError(`Jira API returned ${response.status}`);
+            }
+            const data = (await response.json());
+            return {
+                title: data.fields.summary,
+                description: data.fields.description ?? '',
+                labels: data.fields.labels ?? [],
+                url: `${this.baseUrl}/browse/${key}`,
+                source: 'jira',
+            };
+        }
+        catch (err) {
+            // Re-throw our own errors
+            if (err instanceof IssueNotFoundError ||
+                err instanceof IssueAuthenticationError ||
+                err instanceof IssueServiceUnavailableError) {
+                throw err;
+            }
+            throw new IssueServiceUnavailableError(`Failed to connect to Jira: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}

package/dist/src/infrastructure/services/git/worktree.service.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Git Worktree Service Implementation
+ *
+ * Manages git worktrees using native execFile for process execution.
+ * Uses constructor dependency injection for the command executor
+ * to enable testability without mocking node:child_process directly.
+ */
+import type { IWorktreeService, WorktreeInfo } from '../../../application/ports/output/services/worktree-service.interface.js';
+/**
+ * Type for the command executor dependency.
+ * Matches the promisified signature of child_process.execFile.
+ */
+export type ExecFunction = (file: string, args: string[], options?: object) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare class WorktreeService implements IWorktreeService {
+    private readonly execFile;
+    constructor(execFile: ExecFunction);
+    create(repoPath: string, branch: string, worktreePath: string): Promise<WorktreeInfo>;
+    remove(worktreePath: string): Promise<void>;
+    list(repoPath: string): Promise<WorktreeInfo[]>;
+    exists(repoPath: string, branch: string): Promise<boolean>;
+    getWorktreePath(repoPath: string, branch: string): string;
+    private parseWorktreeOutput;
+    private parseGitError;
+}
+//# sourceMappingURL=worktree.service.d.ts.map

package/dist/src/infrastructure/services/git/worktree.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree.service.d.ts","sourceRoot":"","sources":["../../../../../src/infrastructure/services/git/worktree.service.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACb,MAAM,0EAA0E,CAAC;AAOlF;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,CACzB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE,MAAM,KACb,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEjD,qBACa,eAAgB,YAAW,gBAAgB;IAClB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,YAAY;IAErE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAqBrF,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ3C,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAO/C,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKhE,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IAMzD,OAAO,CAAC,mBAAmB;IA2B3B,OAAO,CAAC,aAAa;CA+BtB"}

package/dist/src/infrastructure/services/git/worktree.service.js

@@ -0,0 +1,112 @@
+/**
+ * Git Worktree Service Implementation
+ *
+ * Manages git worktrees using native execFile for process execution.
+ * Uses constructor dependency injection for the command executor
+ * to enable testability without mocking node:child_process directly.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { injectable, inject } from 'tsyringe';
+import { WorktreeError, WorktreeErrorCode, } from '../../../application/ports/output/services/worktree-service.interface.js';
+import { SHEP_HOME_DIR } from '../filesystem/shep-directory.service.js';
+let WorktreeService = class WorktreeService {
+    execFile;
+    constructor(execFile) {
+        this.execFile = execFile;
+    }
+    async create(repoPath, branch, worktreePath) {
+        try {
+            await this.execFile('git', ['worktree', 'add', worktreePath, '-b', branch], {
+                cwd: repoPath,
+            });
+        }
+        catch (error) {
+            throw this.parseGitError(error);
+        }
+        // Get info about the created worktree
+        const worktrees = await this.list(repoPath);
+        const created = worktrees.find((w) => w.path === worktreePath);
+        if (!created) {
+            throw new WorktreeError('Worktree created but not found in list', WorktreeErrorCode.GIT_ERROR);
+        }
+        return created;
+    }
+    async remove(worktreePath) {
+        try {
+            await this.execFile('git', ['worktree', 'remove', worktreePath], {});
+        }
+        catch (error) {
+            throw this.parseGitError(error);
+        }
+    }
+    async list(repoPath) {
+        const { stdout } = await this.execFile('git', ['worktree', 'list', '--porcelain'], {
+            cwd: repoPath,
+        });
+        return this.parseWorktreeOutput(stdout);
+    }
+    async exists(repoPath, branch) {
+        const worktrees = await this.list(repoPath);
+        return worktrees.some((w) => w.branch === branch);
+    }
+    getWorktreePath(repoPath, branch) {
+        const repoHash = createHash('sha256').update(repoPath).digest('hex').slice(0, 16);
+        const slug = branch.replace(/\//g, '-');
+        return path.join(SHEP_HOME_DIR, 'repos', repoHash, 'wt', slug);
+    }
+    parseWorktreeOutput(output) {
+        if (!output.trim())
+            return [];
+        const worktrees = [];
+        const blocks = output.split('\n\n').filter((b) => b.trim());
+        for (const block of blocks) {
+            const lines = block.split('\n');
+            const wtPath = lines.find((l) => l.startsWith('worktree '))?.slice('worktree '.length) ?? '';
+            const head = lines.find((l) => l.startsWith('HEAD '))?.slice('HEAD '.length) ?? '';
+            const branchLine = lines.find((l) => l.startsWith('branch '));
+            const fullBranch = branchLine?.slice('branch '.length) ?? '';
+            const branch = fullBranch.replace('refs/heads/', '');
+            if (wtPath) {
+                worktrees.push({
+                    path: wtPath,
+                    head,
+                    branch,
+                    isMain: worktrees.length === 0, // First entry is always main
+                });
+            }
+        }
+        return worktrees;
+    }
+    parseGitError(error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes('already exists')) {
+            return new WorktreeError(message, WorktreeErrorCode.ALREADY_EXISTS, error instanceof Error ? error : undefined);
+        }
+        if (message.includes('already checked out') || message.includes('is already checked out')) {
+            return new WorktreeError(message, WorktreeErrorCode.BRANCH_IN_USE, error instanceof Error ? error : undefined);
+        }
+        if (message.includes('not a valid directory') || message.includes('is not a working tree')) {
+            return new WorktreeError(message, WorktreeErrorCode.NOT_FOUND, error instanceof Error ? error : undefined);
+        }
+        return new WorktreeError(message, WorktreeErrorCode.GIT_ERROR, error instanceof Error ? error : undefined);
+    }
+};
+WorktreeService = __decorate([
+    injectable(),
+    __param(0, inject('ExecFunction')),
+    __metadata("design:paramtypes", [Function])
+], WorktreeService);
+export { WorktreeService };

package/dist/src/infrastructure/services/spec/spec-initializer.service.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Spec Initializer Service
+ *
+ * Creates feature specification directories with YAML template files.
+ * Templates match exactly what /shep-kit:new-feature produces,
+ * enabling dogfooding — the CLI and the skill use the same spec format.
+ */
+import type { ISpecInitializerService, SpecInitializerResult } from '../../../application/ports/output/services/spec-initializer.interface.js';
+export declare class SpecInitializerService implements ISpecInitializerService {
+    initialize(basePath: string, slug: string, featureNumber: number, description: string): Promise<SpecInitializerResult>;
+    /**
+     * Scan specs/ for existing NNN-* directories and return the next available number.
+     * Uses the DB-derived hint as a minimum, but always respects filesystem state.
+     */
+    private resolveNextNumber;
+}
+//# sourceMappingURL=spec-initializer.service.d.ts.map

package/dist/src/infrastructure/services/spec/spec-initializer.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-initializer.service.d.ts","sourceRoot":"","sources":["../../../../../src/infrastructure/services/spec/spec-initializer.service.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EACV,uBAAuB,EACvB,qBAAqB,EACtB,MAAM,mEAAmE,CAAC;AA4P3E,qBAAa,sBAAuB,YAAW,uBAAuB;IAC9D,UAAU,CACd,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,qBAAqB,CAAC;IA4BjC;;;OAGG;YACW,iBAAiB;CAoBhC"}

package/dist/src/infrastructure/services/spec/spec-initializer.service.js

@@ -0,0 +1,281 @@
+/**
+ * Spec Initializer Service
+ *
+ * Creates feature specification directories with YAML template files.
+ * Templates match exactly what /shep-kit:new-feature produces,
+ * enabling dogfooding — the CLI and the skill use the same spec format.
+ */
+import { mkdir, readdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Pad a number to 3 digits with leading zeros.
+ */
+function padNumber(n) {
+    return String(n).padStart(3, '0');
+}
+/**
+ * Apply template variable substitution matching init-feature.sh behavior.
+ * Handles both {{VAR}} and { { VAR } } (Prettier-formatted) patterns.
+ */
+function applyTemplate(template, vars) {
+    const replacements = [
+        [/\{\{ ?NNN ?\}\}|\{ \{ NNN \} \}/g, vars.nnn],
+        [/\{\{ ?FEATURE_NAME ?\}\}|\{ \{ FEATURE_NAME \} \}/g, vars.slug],
+        [/\{\{ ?FEATURE_ID ?\}\}|\{ \{ FEATURE_ID \} \}/g, `${vars.nnn}-${vars.slug}`],
+        [/\{\{ ?FEATURE_NUMBER ?\}\}|\{ \{ FEATURE_NUMBER \} \}/g, String(vars.featureNumber)],
+        [/\{\{ ?BRANCH_NAME ?\}\}|\{ \{ BRANCH_NAME \} \}/g, `feat/${vars.nnn}-${vars.slug}`],
+        [/\{\{ ?DATE ?\}\}|\{ \{ DATE \} \}/g, vars.date],
+        [/\{\{ ?TIMESTAMP ?\}\}|\{ \{ TIMESTAMP \} \}/g, vars.timestamp],
+        [/\{\{ ?DESCRIPTION ?\}\}|\{ \{ DESCRIPTION \} \}/g, vars.description],
+    ];
+    let result = template;
+    for (const [pattern, replacement] of replacements) {
+        result = result.replace(pattern, replacement);
+    }
+    return result;
+}
+// ─── YAML Templates ────────────────────────────────────────────────
+// These match .claude/skills/shep-kit:new-feature/templates/ exactly.
+const SPEC_YAML = `# Feature Specification (YAML)
+# This is the source of truth. Markdown is auto-generated from this file.
+
+name: {{FEATURE_NAME}}
+number: {{NNN}}
+branch: feat/{{NNN}}-{{FEATURE_NAME}}
+oneLiner: {{DESCRIPTION}}
+summary: >
+  {{DESCRIPTION}}
+phase: Analysis
+sizeEstimate: M
+
+# Relationships
+relatedFeatures:
+  []
+
+technologies:
+  []
+
+relatedLinks:
+  []
+
+# Open questions (must be resolved before implementation)
+openQuestions:
+  []
+
+# Markdown content (the actual spec)
+content: |
+  ## Problem Statement
+
+  {{DESCRIPTION}}
+
+  ## Success Criteria
+
+  - [ ] TBD
+
+  ## Affected Areas
+
+  | Area | Impact | Reasoning |
+  | ---- | ------ | --------- |
+  | TBD  | TBD    | TBD       |
+
+  ## Dependencies
+
+  None identified.
+
+  ## Size Estimate
+
+  **M** - To be refined during research
+
+  ---
+
+  _Generated by feature agent — proceed with research_
+`;
+const RESEARCH_YAML = `# Research Artifact (YAML)
+# This is the source of truth. Markdown is auto-generated from this file.
+
+name: {{FEATURE_NAME}}
+summary: Technical analysis for {{NNN}}-{{FEATURE_NAME}}
+
+# Relationships
+relatedFeatures: []
+technologies: []
+relatedLinks: []
+
+# Structured technology decisions
+decisions: []
+
+# Open questions (should be resolved by end of research)
+openQuestions: []
+
+# Markdown content (the full research document)
+content: |
+  ## Status
+
+  - **Phase:** Research
+  - **Updated:** {{DATE}}
+
+  ## Technology Decisions
+
+  TBD
+
+  ---
+
+  _To be updated during research phase_
+`;
+const PLAN_YAML = `# Implementation Plan (YAML)
+# This is the source of truth. Markdown is auto-generated from this file.
+
+name: {{FEATURE_NAME}}
+summary: Implementation plan for {{NNN}}-{{FEATURE_NAME}}
+
+# Relationships
+relatedFeatures: []
+technologies: []
+relatedLinks: []
+
+# Structured implementation phases
+phases: []
+
+# File change tracking
+filesToCreate: []
+filesToModify: []
+
+# Open questions (should all be resolved before implementation)
+openQuestions: []
+
+# Markdown content (the full plan document)
+content: |
+  ## Status
+
+  - **Phase:** Planning
+  - **Updated:** {{DATE}}
+
+  ## Implementation Strategy
+
+  TBD
+
+  ---
+
+  _To be updated during planning phase_
+`;
+const TASKS_YAML = `# Task Breakdown (YAML)
+# This is the source of truth. Markdown is auto-generated from this file.
+
+name: {{FEATURE_NAME}}
+summary: Task breakdown for {{NNN}}-{{FEATURE_NAME}}
+
+# Relationships
+relatedFeatures: []
+technologies: []
+relatedLinks: []
+
+# Structured task list
+tasks: []
+
+# Total effort estimate
+totalEstimate: TBD
+
+# Open questions
+openQuestions: []
+
+# Markdown content (the full tasks document)
+content: |
+  ## Status
+
+  - **Phase:** Implementation
+  - **Updated:** {{DATE}}
+
+  ## Task List
+
+  TBD
+
+  ---
+
+  _Task breakdown for implementation tracking_
+`;
+const FEATURE_YAML = `feature:
+  id: '{{FEATURE_ID}}'
+  name: '{{FEATURE_NAME}}'
+  number: {{FEATURE_NUMBER}}
+  branch: '{{BRANCH_NAME}}'
+  lifecycle: 'research'
+  createdAt: '{{TIMESTAMP}}'
+
+status:
+  phase: 'research'
+  progress:
+    completed: 0
+    total: 0
+    percentage: 0
+  currentTask: null
+  lastUpdated: '{{TIMESTAMP}}'
+  lastUpdatedBy: 'feature-agent'
+
+validation:
+  lastRun: null
+  gatesPassed: []
+  autoFixesApplied: []
+
+tasks:
+  current: null
+  blocked: []
+  failed: []
+
+checkpoints:
+  - phase: 'feature-created'
+    completedAt: '{{TIMESTAMP}}'
+    completedBy: 'feature-agent'
+
+errors:
+  current: null
+  history: []
+`;
+const TEMPLATES = [
+    { filename: 'spec.yaml', content: SPEC_YAML },
+    { filename: 'research.yaml', content: RESEARCH_YAML },
+    { filename: 'plan.yaml', content: PLAN_YAML },
+    { filename: 'tasks.yaml', content: TASKS_YAML },
+    { filename: 'feature.yaml', content: FEATURE_YAML },
+];
+export class SpecInitializerService {
+    async initialize(basePath, slug, featureNumber, description) {
+        // Scan existing specs/ directory for highest NNN prefix to avoid collisions
+        // (specs may have been created outside the DB, e.g., via /shep-kit:new-feature)
+        const resolvedNumber = await this.resolveNextNumber(basePath, featureNumber);
+        const nnn = padNumber(resolvedNumber);
+        const specDirName = `${nnn}-${slug}`;
+        const specDir = join(basePath, 'specs', specDirName);
+        // Create the spec directory
+        await mkdir(specDir, { recursive: true });
+        const now = new Date();
+        const date = now.toISOString().split('T')[0];
+        const timestamp = now.toISOString().replace(/\.\d{3}Z$/, 'Z');
+        const vars = { nnn, slug, featureNumber: resolvedNumber, date, timestamp, description };
+        // Write all template files
+        await Promise.all(TEMPLATES.map(({ filename, content }) => writeFile(join(specDir, filename), applyTemplate(content, vars), 'utf-8')));
+        return { specDir, featureNumber: nnn };
+    }
+    /**
+     * Scan specs/ for existing NNN-* directories and return the next available number.
+     * Uses the DB-derived hint as a minimum, but always respects filesystem state.
+     */
+    async resolveNextNumber(basePath, hint) {
+        const specsDir = join(basePath, 'specs');
+        let entries;
+        try {
+            entries = await readdir(specsDir);
+        }
+        catch {
+            // specs/ doesn't exist yet — use hint
+            return hint;
+        }
+        let maxExisting = 0;
+        for (const entry of entries) {
+            const match = entry.match(/^(\d{3})-/);
+            if (match) {
+                maxExisting = Math.max(maxExisting, parseInt(match[1], 10));
+            }
+        }
+        return Math.max(maxExisting + 1, hint);
+    }
+}

package/dist/src/infrastructure/services/web-server.service.d.ts

@@ -10,7 +10,7 @@
  */
 import next from 'next';
 import http from 'node:http';
-import type { IWebServerService } from '../../application/ports/output/web-server-service.interface.js';
+import type { IWebServerService } from '../../application/ports/output/services/web-server-service.interface.js';
 export interface WebServerDeps {
     createNextApp: typeof next;
     createHttpServer: typeof http.createServer;

package/dist/src/infrastructure/services/web-server.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"web-server.service.d.ts","sourceRoot":"","sources":["../../../../src/infrastructure/services/web-server.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,IAAI,MAAM,WAAW,CAAC;AAG7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gEAAgE,CAAC;AAIxG,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,OAAO,IAAI,CAAC;IAC3B,gBAAgB,EAAE,OAAO,IAAI,CAAC,YAAY,CAAC;CAC5C;AAOD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,IAAI;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,CAqB7D;AAED,qBACa,gBAAiB,YAAW,iBAAiB;IACxD,OAAO,CAAC,GAAG,CAAwB;IACnC,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;gBAEzB,IAAI,GAAE,OAAO,CAAC,aAAa,CAAM;IAI7C;;;;;OAKG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,UAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BjE;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAoB5B"}
+{"version":3,"file":"web-server.service.d.ts","sourceRoot":"","sources":["../../../../src/infrastructure/services/web-server.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,IAAI,MAAM,WAAW,CAAC;AAG7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yEAAyE,CAAC;AAIjH,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,OAAO,IAAI,CAAC;IAC3B,gBAAgB,EAAE,OAAO,IAAI,CAAC,YAAY,CAAC;CAC5C;AAOD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,IAAI;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,CAqB7D;AAED,qBACa,gBAAiB,YAAW,iBAAiB;IACxD,OAAO,CAAC,GAAG,CAAwB;IACnC,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;gBAEzB,IAAI,GAAE,OAAO,CAAC,aAAa,CAAM;IAI7C;;;;;OAKG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,UAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BjE;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAoB5B"}

package/dist/src/presentation/cli/commands/agent/approve.command.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Agent Approve Command
+ *
+ * Approves a paused agent run (waiting_approval) and resumes execution.
+ *
+ * Usage:
+ *   shep agent approve <id>
+ */
+import { Command } from 'commander';
+export declare function createApproveCommand(): Command;
+//# sourceMappingURL=approve.command.d.ts.map

package/dist/src/presentation/cli/commands/agent/approve.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approve.command.d.ts","sourceRoot":"","sources":["../../../../../../src/presentation/cli/commands/agent/approve.command.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC,wBAAgB,oBAAoB,IAAI,OAAO,CA8B9C"}

package/dist/src/presentation/cli/commands/agent/approve.command.js

@@ -0,0 +1,42 @@
+/**
+ * Agent Approve Command
+ *
+ * Approves a paused agent run (waiting_approval) and resumes execution.
+ *
+ * Usage:
+ *   shep agent approve <id>
+ */
+import { Command } from 'commander';
+import { container } from '../../../../infrastructure/di/container.js';
+import { ApproveAgentRunUseCase } from '../../../../application/use-cases/agents/approve-agent-run.use-case.js';
+import { colors, messages } from '../../ui/index.js';
+import { resolveAgentRun } from './resolve-run.js';
+export function createApproveCommand() {
+    return new Command('approve')
+        .description('Approve a paused agent run and resume execution')
+        .argument('<id>', 'Agent run ID (or prefix)')
+        .action(async (id) => {
+        try {
+            const resolved = await resolveAgentRun(id);
+            if ('error' in resolved) {
+                messages.error(resolved.error);
+                process.exitCode = 1;
+                return;
+            }
+            const useCase = container.resolve(ApproveAgentRunUseCase);
+            const result = await useCase.execute(resolved.run.id);
+            if (result.approved) {
+                messages.success(`Approved ${colors.accent(resolved.run.id.substring(0, 8))}: ${result.reason}`);
+            }
+            else {
+                messages.error(result.reason);
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            messages.error('Failed to approve agent run', err);
+            process.exitCode = 1;
+        }
+    });
+}