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:

• create [type|URI] <folder> — Scaffolds new projects from named scaffolds, local file:// URIs, or remote HTTP(S) URIs
• 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

Medium Risk
Adds new CLI flows that download/extract and execute scaffold-defined commands, so regressions could impact developer machines and DX; mitigated by HTTPS-only, confirmation prompts, manifest validation, and broad test coverage.

Overview
Adds manifest-driven project scaffolding to the CLI via new subcommands: create (runs SCAFFOLD-MANIFEST.yml steps, supports --agent), verify-scaffold (validates a scaffold without running it), scaffold-cleanup (removes .aidd/ working dirs), and set (persists defaults to ~/.aidd/config.yml).

Introduces a scaffold resolver/runner pipeline that supports named scaffolds, file:// URIs, and HTTPS remote sources (including auto-resolving bare GitHub repo URLs to latest release tarballs), with explicit remote-code confirmation, path-traversal guards, safer YAML parsing/validation, and typed error handling; also bundles next-shadcn (stub) and scaffold-example scaffolds plus extensive unit/E2E coverage.

Improves developer workflow/docs: pre-commit now runs unit tests only (E2E manual), AGENTS.md/CLAUDE.md guidance updated/auto-created, and README/docs expanded for create, scaffold authoring, and aidd-custom/ overrides.

^{Written by Cursor Bugbot for commit 683d794. 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.

[Copilot]

Pull request overview

Copilot reviewed 38 out of 42 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.

[Copilot]

Pull request overview

Copilot reviewed 38 out of 42 changed files in this pull request and generated 1 comment.

---

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

[Copilot]

Pull request overview

Copilot reviewed 40 out of 44 changed files in this pull request and generated 3 comments.

---

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

[Copilot]

The GitHub API request does not include authentication, which means it's subject to GitHub's unauthenticated rate limits (60 requests per hour per IP). For a CLI tool that might be used frequently, consider documenting that users can set a GITHUB_TOKEN environment variable for higher rate limits, or handle 403 rate limit responses with a clear error message explaining the limit and suggesting authentication.

[Copilot]

The activity log states that the extension resolver "Supports named scaffolds, file://, http://, https://" but the implementation at scaffold-resolver.js:177-182 explicitly rejects http:// URIs with an error. The activity log should be updated to remove http:// from the list of supported protocols since only https:// is accepted for security reasons.

Suggested change

	- 🔧 - Extension resolver - Supports named scaffolds, `file://`, `http://`, `https://` with confirmation prompt for remote code
	- 🔧 - Extension resolver - Supports named scaffolds, `file://`, `https://` with confirmation prompt for remote code

[cursor]

verify-scaffold leaks downloaded HTTP/HTTPS scaffolds

Medium Severity

The verify-scaffold command downloads HTTP/HTTPS scaffolds to .aidd/scaffold/ in the current directory but never cleans them up. Unlike the create command which suggests running scaffold-cleanup, verify-scaffold silently leaves the downloaded files behind. A verification command should not leave persistent side effects on the filesystem.

Additional Locations (1)

• bin/aidd.js#L295-L340

 

[Copilot]

Pull request overview

Copilot reviewed 38 out of 42 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]

The validation rules documentation at lines 40-44 does not mention that a step with both run and prompt keys is also rejected as ambiguous. However, this validation is implemented in the code (lib/scaffold-runner.js lines 92-97) and documented elsewhere (ai/scaffolds/SCAFFOLD-AUTHORING.md line 42).

Add a fourth bullet point to the validation rules:

• Any step has both run and prompt keys (ambiguous step)

Suggested change

	- Any step has no recognized keys (`run` or `prompt`)
	- Any step has no recognized keys (`run` or `prompt`)
	- Any step has both `run` and `prompt` keys (ambiguous step)

[Copilot]

The README.md introduces a new section "Customizing aidd Framework for your Project" (lines 448-484) describing an aidd-custom/ directory feature that appears to be documented but not implemented in this PR.

The documentation describes aidd-custom/config.yml and aidd-custom/AGENTS.md as a way to extend or override defaults, and AGENTS.md references this feature (lines 47-49). However, there's no code in this PR that actually reads or processes the aidd-custom/ directory.

This creates a discrepancy where the feature is documented but not functional. Either:

1. Remove the documentation if the feature is not yet implemented
2. Add the implementation to make the feature work as documented
3. Clarify that this is a planned feature and mark it accordingly in the documentation

[Copilot]

There are two very similar scaffold authoring documentation files: docs/scaffold-authoring.md and ai/scaffolds/SCAFFOLD-AUTHORING.md. Both files cover the same topic with nearly identical content but slightly different organization and wording. This creates a maintenance burden as changes need to be kept in sync across both files, and developers may be unsure which one to reference or update.

Consider consolidating these into a single canonical documentation file, or clearly differentiate their purposes (e.g., one for external users vs. one for internal contributors) with appropriate cross-references.

[Copilot]

The path traversal validation at line 121 has a potential edge case issue. The check uses !typeDir.startsWith(scaffoldsRoot + path.sep) which would incorrectly reject a valid scaffold type when typeDir equals scaffoldsRoot exactly (i.e., when type is an empty string or ".").

For example, if type is "." or "", path.resolve(scaffoldsRoot, type) would return scaffoldsRoot itself, which would not start with scaffoldsRoot + path.sep.

The condition should be !typeDir.startsWith(scaffoldsRoot + path.sep) && typeDir !== scaffoldsRoot or use a more robust path containment check like:

const relative = path.relative(scaffoldsRoot, typeDir);
if (relative.startsWith('..') || path.isAbsolute(relative)) {
  throw createError(...);
}

However, this may be intentional behavior (rejecting empty scaffold names), in which case an explicit validation and error message for empty types would be clearer.

Suggested change

	// Reject path traversal: the resolved directory must stay inside scaffoldsRoot
	if (!typeDir.startsWith(scaffoldsRoot + path.sep)) {
	// Explicitly reject empty or "." scaffold types for clarity
	if (!type || type === ".") {
	throw createError({
	...ScaffoldValidationError,
	message: `Invalid scaffold type "${type}": scaffold type name must be non-empty and not ".".`,
	});
	}
	// Reject path traversal: the resolved directory must stay inside scaffoldsRoot
	const relative = path.relative(scaffoldsRoot, typeDir);
	if (relative.startsWith("..") || path.isAbsolute(relative)) {

[cursor]

URL-only argument silently treated as folder name

Medium Severity

resolveCreateArgs lacks a heuristic to detect when a single argument is a URL/URI rather than a folder name. If a user runs npx aidd create https://github.com/org/repo (forgetting the folder), the URL is silently interpreted as the folder name — creating a directory with a mangled URL path and scaffolding the wrong (default) scaffold into it. A check for http://, https://, or file:// prefixes on the single-arg path would catch this and return null (triggering the missing-folder error) or treat it as the type.

Additional Locations (1)

• bin/aidd.js#L224-L231

 

[cursor]

Env var restoration sets string "undefined" polluting tests

Low Severity

The env var restore pattern process.env.AIDD_CUSTOM_CREATE_URI = originalEnv sets the variable to the literal string "undefined" when originalEnv was undefined, because process.env coerces values to strings. This leaves a truthy env var that pollutes subsequent tests. The correct approach is to conditionally delete the env var when the original was undefined. Additionally, these tests don't use try/finally for cleanup, so a test failure skips restoration entirely.

Additional Locations (1)

• lib/scaffold-resolver.test.js#L501-L521

 

[Copilot]

Pull request overview

Copilot reviewed 40 out of 44 changed files in this pull request and generated 7 comments.

---

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

[Copilot]

parseManifest validates the shape of each step, but it doesn’t validate the value types for run/prompt. Because YAML can encode non-strings (arrays/objects/numbers), a manifest could produce spawn argument type errors or unexpected execution semantics. Consider enforcing typeof step.run === "string" and typeof step.prompt === "string" (and rejecting empty strings) as part of validation.

[Copilot]

verifyScaffold returns a generic missing-manifest error without including the actual manifestPath. Including the path makes the output actionable (especially for file:// and downloaded scaffolds) and aligns with the goal of “descriptive” verification errors.

[Copilot]

runVerifyScaffold resolves remote scaffolds into process.cwd()/.aidd/scaffold/, which means verify-scaffold can unexpectedly create a .aidd/ directory in whatever folder the user runs it from (and it doesn’t suggest cleanup). Consider downloading into a temp directory and removing it automatically after verification, or at least documenting/surfacing the cleanup path.

[Copilot]

This epic still claims AIDD_CUSTOM_CREATE_URI supports http:// URIs, but the implementation now rejects insecure HTTP and requires https://. Updating this requirement text will keep the task spec consistent with the current security posture.

[Copilot]

The activity log says the resolver supports http:// URIs, but the current resolver enforces HTTPS-only for remote scaffolds. Please update this entry to avoid documenting insecure HTTP support.

Suggested change

	- 🔧 - Extension resolver - Supports named scaffolds, `file://`, `http://`, `https://` with confirmation prompt for remote code
	- 🔧 - Extension resolver - Supports named scaffolds, `file://` and `https://` (remote scaffolds require HTTPS) with confirmation prompt for remote code

[Copilot]

lib/scaffold-resolver.js relies on the global fetch, which requires Node 18+. Since package.json doesn’t declare an engines.node constraint, users on older Node versions may get a runtime ReferenceError: fetch is not defined. Consider adding an engines field (or a fetch polyfill dependency) to make the requirement explicit.

[Copilot]

runCreate creates the target folder before calling resolveExtension. If the user cancels a remote scaffold confirmation (or resolution fails), this leaves an empty project directory behind even though no scaffolding occurred. Consider deferring ensureDirFn(folder) until after resolveExtensionFn succeeds (or only creating the folder immediately before runManifestFn).

Suggested change

	await ensureDirFn(folder);
	const paths = await resolveExtensionFn({
	folder,
	packageRoot,
	type,
	});
	const paths = await resolveExtensionFn({
	folder,
	packageRoot,
	type,
	});
	await ensureDirFn(folder);

[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]

Env var restoration pollutes process.env with string "undefined"

Medium Severity

When AIDD_CUSTOM_CREATE_URI was never set, originalEnv is undefined. Assigning process.env.AIDD_CUSTOM_CREATE_URI = undefined in Node.js converts it to the string "undefined" rather than deleting the key. Since "undefined" is truthy, the || fallback chain in resolveExtension treats it as a valid scaffold type, potentially causing subsequent tests in the same process to resolve the wrong scaffold or fail unexpectedly.

Additional Locations (1)

• lib/scaffold-resolver.test.js#L510-L511