Add manifest-driven scaffolding with create and scaffold-cleanup commands

[ericelliott]

Overview

This PR implements the npx aidd create epic by adding two new CLI subcommands that enable manifest-driven project scaffolding:

• npx aidd create [type|URI] <folder> — Scaffolds new projects from named scaffolds, local file:// URIs, or remote HTTPS URIs
• npx aidd scaffold-cleanup [folder] — Removes temporary .aidd/ working directories after scaffolding

New Requirements

• For custom URL - assume those point to GitHub repos. Download the latest release into the scaffold folder
• Add documentation explaining how to stage files to be included in the scaffold: use the standard files array in package.json as if you were packaging an npm module

Key Changes

New Modules

lib/scaffold-resolver.js

• Resolves scaffold sources (named, file://, or HTTP/HTTPS URIs) to local paths
• Handles remote code warnings and user confirmation before downloading
• Fetches and caches remote scaffolds in .aidd/scaffold/
• Displays README contents to users
• Supports AIDD_CUSTOM_EXTENSION_URI environment variable for custom defaults

lib/scaffold-runner.js

• Parses YAML manifest files into executable steps
• Executes run steps as shell commands
• Executes prompt steps via agent CLI (default: claude) with proper argument escaping
• Runs bin/extension.js after all manifest steps if present
• Halts on first failure with clear error messages

lib/scaffold-cleanup.js

• Removes .aidd/ directory from scaffolded projects
• Reports whether cleanup was performed or nothing was found

CLI Integration

Updated bin/aidd.js to add:

• create command with --agent flag for specifying the AI agent
• scaffold-cleanup command for post-scaffold cleanup
• Proper error handling and user feedback with chalk colors

Scaffolds

Added two scaffold fixtures:

ai/scaffolds/scaffold-example/ — E2E test fixture

• Initializes npm project with npm init -y
• Installs testing dependencies (riteway, vitest, @playwright/test, error-causes, @paralleldrive/cuid2)
• Configures test script

ai/scaffolds/next-shadcn/ — Default scaffold (placeholder)

• Stub implementation with prompt step
• Full implementation planned for future release

Tests

Added comprehensive test suites:

• lib/scaffold-resolver.test.js (378 lines) — Tests named scaffolds, file:// URIs, HTTP/HTTPS URIs, remote code warnings, and environment variable handling
• lib/scaffold-runner.test.js (329 lines) — Tests manifest parsing, step execution, error handling, and extension.js invocation
• lib/scaffold-cleanup.test.js (70 lines) — Tests directory removal and not-found cases
• bin/create-e2e.test.js (292 lines) — End-to-end tests for create and scaffold-cleanup commands with real file I/O

Security Considerations

• Remote HTTP/HTTPS scaffolds require explicit user confirmation before download
• Warning message includes the full URI for transparency
• Prompt step arguments passed as array elements (no shell injection risk)
• User can cancel remote downloads at confirmation prompt

Test Plan

All changes are covered by automated tests:

• Unit tests verify resolver, runner, and cleanup logic with mocked I/O
• E2E tests verify CLI integration with real file system operations
• Tests use temporary directories and proper cleanup
• CI will run full test suite to validate functionality

https://claude.ai/code/session_01VxNxs3Ly9UQh9TZpJpjG63

---

Note

High Risk
Executes scaffold-defined commands and agent prompts, and adds remote download/extraction and config writing logic; despite validation and HTTPS/confirmation safeguards, this expands the security-sensitive surface area.

Overview
Adds a manifest-driven scaffolding workflow to the aidd CLI via new create, verify-scaffold, scaffold-cleanup, and set create-uri commands, including support for named scaffolds, file:// scaffolds, and HTTPS-only remote scaffolds with explicit user confirmation.

Introduces a YAML-based SCAFFOLD-MANIFEST.yml runner (run shell steps + prompt steps executed via a configurable agent) with stricter validation/safe YAML parsing, plus GitHub repo URL resolution to latest release tarballs and a .aidd/ working directory cleanup flow.

Updates installation flow and docs to include Claude Code support (--claude + .claude symlink), automatic CLAUDE.md creation, new agent skill /aidd-fix, scaffold authoring documentation, and adjusts the pre-commit hook to run unit tests only (E2E run manually).

^{Written by Cursor Bugbot for commit f355dc3. This will update automatically on new commits. Configure here.}

[ericelliott]

@cursor please /review

[cursor]

✅ No technical debt markers (TODO/FIXME) in new code

9. Specific Issues Summary

Critical:
None

High:

1. Missing error-causes usage - Should use project's error handling standard
2. SSRF vulnerability - No validation on HTTP/HTTPS URLs to prevent SSRF attacks

Medium:
3. No integrity checks - Remote scaffolds lack checksum/signature verification
4. Missing JSDoc - Public API functions lack minimal docblocks

Low:
5. Security logging - Consider adding audit trail for scaffold operations
6. Error context - Errors should include more structured metadata

10. Actionable Recommendations

Must Fix (Before Merge):

1. Add error-causes support:

// In lib/scaffold-resolver.js
import { createError } from "error-causes";

// Replace all throw new Error() with:
throw createError({
  name: 'ScaffoldError',
  message: 'Remote extension download cancelled by user.',
  code: 'USER_CANCELLED',
  uri: effectiveType
});

2. Add SSRF protection:

import { URL } from 'url';

const validateHttpUrl = (urlString) => {
  try {
    const url = new URL(urlString);
    const hostname = url.hostname;
    
    // Block private IP ranges
    if (
      hostname === 'localhost' ||
      hostname.startsWith('127.') ||
      hostname.startsWith('10.') ||
      hostname.startsWith('192.168.') ||
      hostname.startsWith('169.254.') ||
      hostname.match(/^172\.(1[6-9]|2[0-9]|3[0-1])\./)
    ) {
      throw createError({
        name: 'InvalidScaffoldUri',
        message: 'Private IP addresses are not allowed',
        code: 'PRIVATE_IP_BLOCKED',
        uri: urlString
      });
    }
    
    return true;
  } catch (err) {
    throw createError({
      name: 'InvalidScaffoldUri',
      message: 'Invalid URL format',
      code: 'INVALID_URL',
      uri: urlString,
      cause: err
    });
  }
};

// Use before fetching
if (isHttpUrl(effectiveType)) {
  validateHttpUrl(effectiveType);
  // ... rest of logic
}

Should Fix (Post-Merge):

3. Add JSDoc to public APIs:

/**
 * Resolves a scaffold source to local file paths.
 * Supports named scaffolds, file:// URIs, and HTTP(S) URIs.
 * @param {Object} options - Configuration options
 * @param {string} [options.type] - Scaffold type: name, file://, or http(s):// URI
 * @param {string} options.folder - Target folder path
 * @param {string} [options.packageRoot] - Package root directory
 * @returns {Promise<{manifestPath: string, extensionJsPath: string, readmePath: string}>}
 */

4. Add integrity verification for remote scaffolds:

   • Consider supporting a .sha256 file alongside remote scaffolds
   • Verify checksum before executing

5. Add security logging:

   • Log scaffold downloads with timestamps
   • Log executed commands for audit trail

11. Vision Alignment

✅ The PR aligns well with the vision document:

• Enhances developer experience with clear, intuitive commands
• Follows the "universal compatibility" principle
• Open-source first approach
• Professional quality implementation

Final Verdict

Status: ⚠️ Conditionally Approve - High quality implementation with excellent test coverage, but requires two security fixes before merge:

1. Must add error-causes for consistency with project standards
2. Must add SSRF protection for HTTP/HTTPS URLs

Overall Quality: 8.5/10

• Excellent code organization and testing
• Good architectural patterns
• Strong adherence to functional programming principles
• Security considerations present but incomplete

Test Coverage: 10/10 - Comprehensive and well-written

Code Quality: 9/10 - Clean, functional, follows project standards (minus error-causes)

Security: 7/10 - Good injection prevention, but SSRF risk and missing integrity checks

The implementation is solid and the test coverage is exemplary. Once the two security issues are addressed, this will be an excellent addition to the codebase.

 

[Copilot]

Pull request overview

Implements manifest-driven project scaffolding for the aidd CLI by adding create and scaffold-cleanup subcommands, along with the supporting resolver/runner/cleanup libraries, scaffold fixtures, and test coverage.

Changes:

• Added scaffold source resolution (named scaffolds, file://, http(s):// with confirmation) and a manifest runner for run/prompt steps.
• Integrated new create and scaffold-cleanup subcommands into the CLI.
• Added scaffold fixtures (scaffold-example, next-shadcn) plus unit + E2E test suites.

Reviewed changes

Copilot reviewed 17 out of 20 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tasks/npx-aidd-create-epic.md	Marks the epic status as DONE.
lib/scaffold-runner.js	New manifest parser + step runner (run/prompt + optional extension.js).
lib/scaffold-runner.test.js	Unit tests for manifest parsing and execution ordering/failure behavior.
lib/scaffold-resolver.js	New resolver for named/file/http scaffolds with caching under .aidd/scaffold.
lib/scaffold-resolver.test.js	Unit tests for named/file/http resolution, confirmation, and env var defaulting.
lib/scaffold-cleanup.js	New cleanup helper to remove .aidd/ working directory.
lib/scaffold-cleanup.test.js	Unit tests for cleanup behavior and default folder handling.
bin/aidd.js	Adds create (with --agent) and scaffold-cleanup subcommands.
bin/create-e2e.test.js	E2E tests for create, env defaulting, --agent, and cleanup.
ai/scaffolds/index.md	Adds index entry for scaffold directory.
ai/index.md	Links to ai/scaffolds/ from the top-level AI index.
ai/scaffolds/scaffold-example/README.md	Documents the scaffold-example fixture scaffold.
ai/scaffolds/scaffold-example/SCAFFOLD-MANIFEST.yml	Defines manifest steps for the E2E fixture (npm init/pkg/test/install).
ai/scaffolds/scaffold-example/index.md	Generated directory index for scaffold-example.
ai/scaffolds/scaffold-example/bin/index.md	Generated directory index for bin/.
ai/scaffolds/next-shadcn/README.md	Documents default scaffold (stub).
ai/scaffolds/next-shadcn/SCAFFOLD-MANIFEST.yml	Placeholder manifest with a prompt step.
ai/scaffolds/next-shadcn/index.md	Generated directory index for next-shadcn.
activity-log.md	Adds an entry describing the new commands and modules.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 20 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 25 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

@ericelliott I've opened a new pull request, #99, to work on those changes. Once the pull request is ready, I'll request review from you.

[cursor]

CLAUDE.md modified on every second install run

Medium Severity

ensureClaudeMd creates CLAUDE.md with AGENTS_MD_CONTENT on first run, but AGENTS_MD_CONTENT never contains the literal string "AGENTS.md". On the next npx aidd install, the existingContent.includes("AGENTS.md") check on the tool's own content always fails, causing it to append an unnecessary "see AGENTS.md" reference to a file it just created. This contradicts the stated intent of "never overwrites an existing CLAUDE.md" — the file is silently modified on every second invocation.

 

[cursor]

Cleanup tip breaks for paths containing spaces

Low Severity

The cleanupTip is built via simple string interpolation: `npx aidd scaffold-cleanup ${folder}`. If folder is an absolute path containing spaces (e.g. /home/user/my project), the suggested command becomes npx aidd scaffold-cleanup /home/user/my project, which the shell would split into two separate arguments. The path needs to be quoted in the tip string so the user can copy-paste it safely.

 

[Copilot]

Pull request overview

Copilot reviewed 39 out of 43 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cursor]

create help omits user config fallback

Medium Severity

The create command help text says [type] defaults to AIDD_CUSTOM_CREATE_URI and then "next-shadcn", but the actual resolver also falls back to ~/.aidd/config.yml (create-uri). This mismatch makes npx aidd set create-uri ... look ineffective and can lead to incorrect CLI usage.

 

[cursor]

Single http:// arg treated as folder

Medium Severity

resolveCreateArgs returns null for a single https:///file:// arg (to avoid mangled folder creation) but intentionally allows a single http:// arg to fall through as a folder name. This can try to ensureDir on a path containing : and /, producing confusing filesystem behavior instead of a clear “missing folder / unsupported URI” error.

 

[Copilot]

Pull request overview

Copilot reviewed 39 out of 43 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cursor]

Single http URL becomes folder name

Medium Severity

resolveCreateArgs() treats a single http://... argument as a folder name (while rejecting single https:///file://). This can silently create a directory literally named like a URL and then scaffold using the default type, which looks like “create from URL” succeeded but actually ignored the URL.

 

[cursor]

Verifier rejects extension-only scaffolds

Low Severity

verifyScaffold() marks manifests with no steps as invalid ("scaffold would do nothing"), but a scaffold can still do meaningful work via bin/extension.js (which runManifest() runs even when steps is empty). This makes verify-scaffold report false negatives for extension-driven scaffolds.

 

[cursor]

Bugbot Autofix prepared fixes for 2 of the 2 bugs found in the latest run.

• ✅ Fixed: Single http URL becomes folder name
  • Added http:// to the URI detection regex in resolveCreateArgs to prevent creating weirdly-named directories when folder argument is missing.
• ✅ Fixed: Verifier rejects extension-only scaffolds
  • Modified verifyScaffold to check for bin/extension.js existence before rejecting empty manifests, allowing valid extension-only scaffolds.

Or push these changes by commenting:

@cursor push bfc9138408

Preview (bfc9138408)

diff --git a/lib/scaffold-create.js b/lib/scaffold-create.js
--- a/lib/scaffold-create.js
+++ b/lib/scaffold-create.js
@@ -22,9 +22,8 @@
   // If no folder was given and the sole argument looks like a URI, the user
   // most likely forgot the folder argument. Return null so the caller emits
   // "missing required argument 'folder'" rather than creating a directory
-  // with a mangled URL path. http:// is intentionally excluded — it is not
-  // a supported protocol.
-  if (folder === undefined && /^(https|file):\/\//i.test(typeOrFolder)) {
+  // with a mangled URL path.
+  if (folder === undefined && /^(https?|file):\/\//i.test(typeOrFolder)) {
     return null;
   }
 

diff --git a/lib/scaffold-create.test.js b/lib/scaffold-create.test.js
--- a/lib/scaffold-create.test.js
+++ b/lib/scaffold-create.test.js
@@ -32,13 +32,13 @@
     });
   });
 
-  test("does not reject http:// as a single arg (unsupported — falls through to folder)", () => {
+  test("returns null when single arg is an http:// URI (folder omitted)", () => {
     const result = resolveCreateArgs("http://example.com/scaffold", undefined);
     assert({
-      given: "an http:// URL (unsupported protocol) as the sole arg",
-      should: "not return null — http is not a recognised URI scheme",
-      actual: result !== null,
-      expected: true,
+      given: "only an http:// URL with no folder",
+      should: "return null to signal missing folder",
+      actual: result,
+      expected: null,
     });
   });
 

diff --git a/lib/scaffold-verifier.js b/lib/scaffold-verifier.js
--- a/lib/scaffold-verifier.js
+++ b/lib/scaffold-verifier.js
@@ -1,3 +1,4 @@
+import path from "path";
 import fs from "fs-extra";
 
 import { parseManifest } from "./scaffold-runner.js";
@@ -24,8 +25,14 @@
   }
 
   if (steps.length === 0) {
-    errors.push("Manifest contains no steps — scaffold would do nothing");
-    return { errors, valid: false };
+    const scaffoldDir = path.dirname(manifestPath);
+    const extensionJsPath = path.join(scaffoldDir, "bin/extension.js");
+    const extensionExists = await fs.pathExists(extensionJsPath);
+
+    if (!extensionExists) {
+      errors.push("Manifest contains no steps — scaffold would do nothing");
+      return { errors, valid: false };
+    }
   }
 
   return { errors: [], valid: true };

diff --git a/lib/scaffold-verifier.test.js b/lib/scaffold-verifier.test.js
--- a/lib/scaffold-verifier.test.js
+++ b/lib/scaffold-verifier.test.js
@@ -87,20 +87,38 @@
     });
   });
 
-  test("returns valid=false when manifest has no steps", async () => {
+  test("returns valid=false when manifest has no steps and no extension", async () => {
     const manifestPath = path.join(tempDir, "SCAFFOLD-MANIFEST.yml");
     await fs.writeFile(manifestPath, "steps: []\n");
 
     const result = await verifyScaffold({ manifestPath });
 
     assert({
-      given: "a manifest with an empty steps array",
+      given: "a manifest with an empty steps array and no extension.js",
       should: "return valid false (scaffold would do nothing)",
       actual: result.valid,
       expected: false,
     });
   });
 
+  test("returns valid=true when manifest has no steps but has extension.js", async () => {
+    const manifestPath = path.join(tempDir, "SCAFFOLD-MANIFEST.yml");
+    const extensionPath = path.join(tempDir, "bin/extension.js");
+
+    await fs.writeFile(manifestPath, "steps: []\n");
+    await fs.ensureDir(path.dirname(extensionPath));
+    await fs.writeFile(extensionPath, "console.log('extension');\n");
+
+    const result = await verifyScaffold({ manifestPath });
+
+    assert({
+      given: "a manifest with no steps but with bin/extension.js",
+      should: "return valid true (extension can still do work)",
+      actual: result.valid,
+      expected: true,
+    });
+  });
+
   test("returns valid=true for manifest with prompt steps", async () => {
     const manifestPath = path.join(tempDir, "SCAFFOLD-MANIFEST.yml");
     await fs.writeFile(

_{This Bugbot Autofix run was free. To enable Autofix for future PRs, go to the Cursor dashboard.}

[Copilot]

Pull request overview

Copilot reviewed 45 out of 49 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cursor]

Non-idempotent CLAUDE.md creation on repeated installs

Medium Severity

ensureClaudeMd creates CLAUDE.md with AGENTS_MD_CONTENT, which does not contain the literal string "AGENTS.md". On a subsequent npx aidd run, the existingContent.includes("AGENTS.md") check returns false, so the function appends a redundant AGENTS.md reference to a file it just created. This makes the installer non-idempotent — the second run always modifies CLAUDE.md unnecessarily. A different detection mechanism (e.g., checking for the template's heading) would avoid modifying the tool's own output on re-run.

Additional Locations (1)

• lib/agents-md.js#L275-L281

 

[cursor]

Env var restore sets "undefined" string instead of deleting

Low Severity

Restoring process.env.AIDD_CUSTOM_CREATE_URI by assigning a saved value that was undefined coerces it to the string "undefined" instead of removing the variable. process.env stringifies all assigned values. This pollutes the environment for subsequent tests, potentially causing resolveExtension to treat "undefined" as a scaffold type. The cleanup needs a conditional delete when the original value was not set.

Additional Locations (1)

• lib/scaffold-resolver.test.js#L505-L515

 

[cursor]

Duplicate error type definitions across modules

Low Severity

ValidationError and FileSystemError are redefined as standalone objects in symlinks.js rather than reusing the identical definitions from the errorCauses call in cli-core.js. If the error codes or messages are updated in one location, the other can easily drift out of sync, causing handleCliErrors to fail to dispatch correctly for symlink errors.

 

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[cursor]

Unsafe YAML parsing allows code execution

Medium Severity

The yaml.load() call in readConfig doesn't specify a schema, defaulting to DEFAULT_SCHEMA which enables YAML type tags like !!js/function and !!js/regexp that execute arbitrary JavaScript. While ~/.aidd/config.yml is user-controlled, an attacker who can influence this file (through compromised dependencies or social engineering) could inject malicious YAML that executes when the user runs npx aidd create. The same codebase correctly uses yaml.JSON_SCHEMA in scaffold-runner.js line 55 to prevent this.

 

[Copilot]

Pull request overview

Copilot reviewed 53 out of 58 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

readConfig uses yaml.load(content) with the default schema, which allows YAML tags that can deserialize into non-plain JS types (e.g. RegExp/functions). Since the returned value is used as a string (config["create-uri"]), a tagged value can cause runtime type errors or unexpected behavior. Parse with a restricted schema (e.g. yaml.JSON_SCHEMA) and/or validate that the loaded config is a plain object with string values before returning it.

[Copilot]

parseManifest validates the presence of run/prompt keys but does not validate that their values are strings. A manifest like - run: 42 will pass validation, then runManifest/spawn will throw a raw TypeError instead of a typed ScaffoldValidationError/ScaffoldStepError. Add a validation that step.run / step.prompt are strings (and include the step number/type in the error).

[ericelliott]

We are not going to have a standard extension.js because you can just run any arbitrary command during install.