container-superposition 0.1.4 → 0.1.6

package/dist/tool/utils/backup.js

@@ -0,0 +1,123 @@
+/**
+ * Backup utilities — shared by init/regen and adopt commands.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import chalk from 'chalk';
+import { appendGitignoreSection } from './gitignore.js';
+/**
+ * Detect whether a directory (or any of its parents) is inside a git repository.
+ * First tries `git rev-parse --git-dir`; if git is unavailable, falls back to
+ * walking up the directory tree looking for a `.git` entry.
+ */
+export function isInsideGitRepo(dirPath) {
+    try {
+        execSync('git rev-parse --git-dir', { cwd: dirPath, stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        // git command failed (not a repo) or git is not installed — walk up looking for .git
+        let current = path.resolve(dirPath);
+        while (true) {
+            if (fs.existsSync(path.join(current, '.git'))) {
+                return true;
+            }
+            const parent = path.dirname(current);
+            if (parent === current) {
+                break; // reached filesystem root
+            }
+            current = parent;
+        }
+        return false;
+    }
+}
+/**
+ * Recursively copy a directory.
+ */
+export async function copyDirectory(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            await copyDirectory(srcPath, destPath);
+        }
+        else {
+            fs.copyFileSync(srcPath, destPath);
+        }
+    }
+}
+/**
+ * Create a timestamped backup of an existing devcontainer directory.
+ * Returns the path of the backup directory, or null if there was nothing to back up.
+ */
+export async function createBackup(outputPath, backupDir) {
+    const devcontainerJsonPath = path.join(outputPath, 'devcontainer.json');
+    const dockerComposePath = path.join(outputPath, 'docker-compose.yml');
+    const devcontainerSubdir = path.join(outputPath, '.devcontainer');
+    const manifestPath = path.join(outputPath, 'superposition.json');
+    const hasDevcontainerJson = fs.existsSync(devcontainerJsonPath);
+    const hasDockerCompose = fs.existsSync(dockerComposePath);
+    const hasDevcontainerSubdir = fs.existsSync(devcontainerSubdir) && fs.statSync(devcontainerSubdir).isDirectory();
+    const hasManifest = fs.existsSync(manifestPath);
+    if (!hasDevcontainerJson && !hasDockerCompose && !hasDevcontainerSubdir && !hasManifest) {
+        return null; // Nothing to backup
+    }
+    const timestamp = new Date()
+        .toISOString()
+        .replace(/:/g, '-')
+        .replace(/\..+/, '')
+        .replace('T', '-');
+    const resolvedOutputPath = path.resolve(outputPath);
+    const outputParentDir = path.dirname(resolvedOutputPath);
+    const outputBaseName = path.basename(resolvedOutputPath);
+    const backupBaseName = outputBaseName === '.devcontainer' ? '.devcontainer' : outputBaseName;
+    const backupPath = backupDir
+        ? path.resolve(backupDir)
+        : path.join(outputParentDir, `${backupBaseName}.backup-${timestamp}`);
+    fs.mkdirSync(backupPath, { recursive: true });
+    if (hasDevcontainerJson) {
+        fs.copyFileSync(devcontainerJsonPath, path.join(backupPath, 'devcontainer.json'));
+    }
+    if (hasDockerCompose) {
+        fs.copyFileSync(dockerComposePath, path.join(backupPath, 'docker-compose.yml'));
+    }
+    if (hasDevcontainerSubdir) {
+        await copyDirectory(devcontainerSubdir, path.join(backupPath, '.devcontainer'));
+    }
+    if (hasManifest) {
+        fs.copyFileSync(manifestPath, path.join(backupPath, 'superposition.json'));
+    }
+    const otherFiles = ['.env', '.env.example', '.gitignore', 'features', 'scripts'];
+    for (const file of otherFiles) {
+        const srcPath = path.join(outputPath, file);
+        if (fs.existsSync(srcPath)) {
+            const destPath = path.join(backupPath, file);
+            if (fs.statSync(srcPath).isDirectory()) {
+                await copyDirectory(srcPath, destPath);
+            }
+            else {
+                fs.copyFileSync(srcPath, destPath);
+            }
+        }
+    }
+    return backupPath;
+}
+/**
+ * Append backup glob patterns to the project-root .gitignore (idempotent).
+ */
+export function ensureBackupPatternsInGitignore(outputPath) {
+    const projectRoot = path.dirname(path.resolve(outputPath));
+    const gitignorePath = path.join(projectRoot, '.gitignore');
+    const written = appendGitignoreSection(gitignorePath, 'container-superposition backups', [
+        '.devcontainer.backup-*/',
+        '*.backup-*',
+        'superposition.json.backup-*',
+    ]);
+    if (written) {
+        console.log(chalk.dim('   📝 Updated .gitignore with backup patterns'));
+    }
+}
+//# sourceMappingURL=backup.js.map

package/dist/tool/utils/backup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.js","sourceRoot":"","sources":["../../../tool/utils/backup.ts"],"names":[],"mappings":"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"}

package/docs/README.md

@@ -2,6 +2,11 @@
 
 Complete documentation for the container-superposition devcontainer scaffolding system.
 
+## Spec-First Development
+
+Feature work is governed by specs committed under `docs/specs/`. Implementation
+must not begin until the relevant spec is committed and reviewed.
+
 ## 📚 Documentation Index
 
 ### Getting Started
@@ -19,10 +24,15 @@ Complete documentation for the container-superposition devcontainer scaffolding
 
 ### User Guides
 
+- **[Adopt Command](adopt.md)** - Migrate an existing `.devcontainer/` to the overlay-based workflow
+- **[Hash Command](hash.md)** - Deterministic environment fingerprint for drift detection and reproducibility
 - **[Presets Guide](presets.md)** - Using stack presets for common development scenarios
 - **[Messaging Comparison](messaging-comparison.md)** - Choosing between RabbitMQ, Redpanda, and NATS
 - **[Messaging Quick Start](messaging-quick-start.md)** - Getting started with messaging overlays
 - **[Observability Workflow](observability-workflow.md)** - Setting up monitoring and tracing
+- **[Workflows and Regeneration](workflows.md)** - Regeneration, backups, and manifest-based workflows
+- **[Filesystem Contract](filesystem-contract.md)** - What the tool writes and what to edit
+- **[Security Considerations](security.md)** - Development-only risks and best practices
 
 ### Development
 
@@ -209,7 +219,7 @@ When published to npm, includes:
 - ✅ Type definitions and schema (`tool/schema/`)
 - ✅ Documentation
 
-**Package size**: ~122 KB compressed, ~462 KB unpacked
+**Package size**: Varies by release (use `npm pack --dry-run`)
 
 ## 🤝 Contributing
 
@@ -228,7 +238,7 @@ MIT - See [LICENSE](../LICENSE)
 
 - **Repository**: <https://github.com/veggerby/container-superposition>
 - **Issues**: <https://github.com/veggerby/container-superposition/issues>
-- **npm Package**: <https://www.npmjs.com/package/container-superposition> (once published)
+- **npm Package**: <https://www.npmjs.com/package/container-superposition>
 
 ## 🆘 Support
 

package/docs/adopt.md

@@ -0,0 +1,202 @@
+# Adopt Command
+
+The `adopt` command helps you **migrate an existing `.devcontainer/` configuration** to Container Superposition's overlay-based workflow.
+
+It scans your current `devcontainer.json` and any linked `docker-compose.yml` files, matches their contents against all available overlays, and produces:
+
+1. **`superposition.json`** — the manifest written to the **project root** (next to your `src/`, `package.json`, etc.), ready to commit and share with your team
+2. **`.superposition.yml`** — an optional repository-root project file when you pass `--project-file`, using the same inferred stack, overlays, output path, and supported customizations
+3. **`.devcontainer/custom/devcontainer.patch.json`** — any config that has no overlay equivalent (custom features, extensions, mounts, remoteEnv, etc.)
+4. **`.devcontainer/custom/docker-compose.patch.yml`** — any compose services that have no overlay equivalent
+
+The custom patches in `custom/` are automatically merged on every `regen`, so your project-specific configuration is never lost.
+
+## Quick Start
+
+```bash
+# Analyse your existing .devcontainer/ (prints a report, writes nothing)
+npx container-superposition adopt --dry-run
+
+# Run the analysis and write the generated files
+npx container-superposition adopt
+
+# Also write a repository-root project file for project-config workflows
+npx container-superposition adopt --project-file
+
+# Force-overwrite any existing superposition.json / custom/ files
+npx container-superposition adopt --force
+```
+
+## Docker Compose Devcontainers
+
+`adopt` fully supports compose-based devcontainers. It reads the
+`dockerComposeFile` field in `devcontainer.json` to locate the right compose
+file(s), including:
+
+- **Single file** (string): `"dockerComposeFile": "docker-compose.yml"`
+- **Multiple files** (array): `"dockerComposeFile": ["base.yml", "override.yml"]`
+- **Relative paths** pointing outside the `.devcontainer/` directory:
+  `"dockerComposeFile": "../docker-compose.yml"`
+
+All referenced compose files are analysed. Every service with a recognised
+image (postgres, redis, grafana, jaeger, …) is mapped to the corresponding
+overlay. Services with no overlay equivalent are written to
+`custom/docker-compose.patch.yml` so they are preserved across regenerations.
+
+## How It Works
+
+### Detection
+
+The command builds its detection tables **dynamically from the overlay registry** — there are no hardcoded overlay names. For every overlay it reads:
+
+| Source                                                         | What is extracted         |
+| -------------------------------------------------------------- | ------------------------- |
+| `devcontainer.patch.json` → `features`                         | Feature URI → overlay ID  |
+| `devcontainer.patch.json` → `customizations.vscode.extensions` | Extension ID → overlay ID |
+| `docker-compose.yml` → service `image`                         | Image prefix → overlay ID |
+
+When multiple overlays share the same feature (e.g. both `nodejs` and `bun`
+include the Node.js devcontainer feature), the one whose ID best matches the
+feature's own name wins.
+
+### Detection signals (in priority order)
+
+1. **Devcontainer features** — e.g. `ghcr.io/devcontainers/features/node:1` → `nodejs` (confidence: **exact**)
+2. **Docker Compose service images** — e.g. `postgres:16-alpine` → `postgres` (confidence: **exact**)
+3. **VS Code extensions** — e.g. `ms-python.python` → `python` (confidence: **heuristic**)
+4. **Remote environment variables** — e.g. `POSTGRES_*` → `postgres` (confidence: **heuristic**)
+
+### Unmatched items → `custom/`
+
+Anything that cannot be mapped to an overlay is preserved in the `custom/`
+directory, which is merged automatically on every `regen`:
+
+| Unmatched item                                  | Written to                                                            |
+| ----------------------------------------------- | --------------------------------------------------------------------- |
+| Unknown features                                | `custom/devcontainer.patch.json` → `features`                         |
+| Unknown VS Code extensions                      | `custom/devcontainer.patch.json` → `customizations.vscode.extensions` |
+| Custom `mounts`                                 | `custom/devcontainer.patch.json` → `mounts`                           |
+| Non-default `remoteUser`                        | `custom/devcontainer.patch.json` → `remoteUser`                       |
+| Custom `postCreateCommand` / `postStartCommand` | `custom/devcontainer.patch.json`                                      |
+| Unknown compose services                        | `custom/docker-compose.patch.yml` → `services`                        |
+
+## Backup Behaviour
+
+The same backup logic as `regen` is used:
+
+| Condition                    | What happens                   |
+| ---------------------------- | ------------------------------ |
+| Inside a git repo (default)  | No backup — git tracks history |
+| Outside a git repo (default) | Backup created automatically   |
+| `--backup` flag              | Backup always created          |
+| `--no-backup` flag           | Backup always skipped          |
+
+Backups are placed next to the `.devcontainer/` directory as
+`.devcontainer.backup-<timestamp>/`, and the corresponding glob patterns are
+automatically added to `.gitignore`.
+
+## Options
+
+| Option                | Description                                                                   |
+| --------------------- | ----------------------------------------------------------------------------- |
+| `-d, --dir <path>`    | Path to the existing `.devcontainer/` directory (default: `./.devcontainer`)  |
+| `--dry-run`           | Print the analysis without writing any files                                  |
+| `--force`             | Overwrite existing `superposition.json` / `custom/` files                     |
+| `--backup`            | Force a backup even when inside a git repo                                    |
+| `--no-backup`         | Disable backup creation even when it would normally be performed              |
+| `--backup-dir <path>` | Custom backup directory location                                              |
+| `--project-file`      | Also write a repository-root project config (`.superposition.yml` by default) |
+| `--json`              | Output analysis as JSON (useful for scripting)                                |
+
+## Example Output
+
+```
+╭──────────────────────╮
+│  🔍 Adopt Analysis   │
+╰──────────────────────╯
+
+Analysing .devcontainer/devcontainer.json...
+Analysing .devcontainer/docker-compose.yml...
+
+Detected features / services → suggested overlays
+────────────────────────────────────────────────────────────────────────────────
+Source                                                    →   Overlay               Confidence
+────────────────────────────────────────────────────────────────────────────────────────────────
+ghcr.io/devcontainers/features/node:1                     →   nodejs                exact
+service: postgres (image: postgres:16-alpine)             →   postgres              exact
+service: redis (image: redis:7-alpine)                    →   redis                 exact
+
+Items with no overlay equivalent → custom/
+────────────────────────────────────────────────────────────────────────────────
+Source                                                      Action
+────────────────────────────────────────────────────────────────────────────────────────────────
+ghcr.io/corp/internal-tools:1                               No overlay covers this feature — preserve in custom/devcontainer.patch.json
+service: my-app (image: my-registry/my-app:latest)          No overlay covers this service — preserve in custom/docker-compose.patch.yml
+
+Suggested command:
+  container-superposition init --stack compose --language nodejs --database postgres,redis
+
+💡 Custom patches will be written to .devcontainer/custom/ to preserve
+   any configuration that has no overlay equivalent.
+```
+
+## After Adopt
+
+Once `adopt` has run:
+
+1. **Review `superposition.json`** — verify the detected overlays are correct; add or remove as needed.
+2. **Review `.superposition.yml` if you generated one** — it captures the same inferred setup as a repository-root project file, including inline supported customizations.
+3. **Review `custom/` patches** — inspect what was preserved and trim anything no longer needed.
+4. **Regenerate** — rebuild your `.devcontainer/` from the manifest or project file:
+    ```bash
+    npx container-superposition regen
+    ```
+5. **Commit `superposition.json`**, the optional project file, and, if applicable, `custom/` patches.
+
+## JSON Output
+
+Use `--json` to get machine-readable output for scripting or CI workflows:
+
+```bash
+npx container-superposition adopt --dry-run --json | jq .suggestedOverlays
+```
+
+The JSON object contains:
+
+```jsonc
+{
+    "dir": "/absolute/path/to/.devcontainer",
+    "detections": [
+        {
+            "source": "ghcr.io/devcontainers/features/node:1",
+            "overlayId": "nodejs",
+            "confidence": "exact",
+            "sourceType": "feature",
+        },
+        // ...
+    ],
+    "unmatchedItems": [
+        {
+            "source": "ghcr.io/corp/internal-tools:1",
+            "reason": "No overlay covers this feature — preserve in custom/devcontainer.patch.json",
+        },
+        // ...
+    ],
+    "customDevcontainerPatch": {
+        /* or null */
+    },
+    "customComposePatch": {
+        /* or null */
+    },
+    "suggestedStack": "compose",
+    "suggestedOverlays": ["nodejs", "postgres", "redis"],
+    "suggestedCommand": "container-superposition init --stack compose --language nodejs --database postgres,redis",
+}
+```
+
+## See Also
+
+- [Team Workflow](team-workflow.md) — Manifest-first team collaboration workflow
+- [Custom Patches](custom-patches.md) — How `custom/` patches are merged
+- [Workflows and Regeneration](workflows.md) — Regeneration and backup details
+- [Quick Reference](quick-reference.md) — All commands at a glance

package/docs/custom-patches.md

@@ -417,7 +417,7 @@ The `superposition.json` manifest tracks whether customizations are present:
 
 ```json
 {
-    "version": "0.1.0",
+    "version": "X.Y.Z",
     "baseTemplate": "compose",
     "overlays": ["nodejs", "postgres"],
     "customizations": {

package/docs/discovery-commands.md

@@ -223,6 +223,9 @@ The `plan` command shows a dry-run preview of what will be generated, including
 ```bash
 # Preview generation for postgres and grafana
 npx container-superposition plan --stack compose --overlays postgres,grafana
+
+# Preview generation from an existing manifest
+npx container-superposition plan --from-manifest .devcontainer/superposition.json
 ```
 
 **Output:**
@@ -265,12 +268,18 @@ Files to Create/Modify:
 
 ### Required Options
 
-- `--stack <type>` - Base template: `plain` or `compose`
+- `--stack <type>` - Base template: `plain` or `compose` when planning from explicit overlays
 - `--overlays <list>` - Comma-separated list of overlay IDs
 
+### Manifest Input
+
+- `--from-manifest <path>` - Load stack and overlay roots from an existing `superposition.json`
+- Use either `--overlays` or `--from-manifest` for a given `plan` invocation
+
 ### Optional Options
 
 - `--port-offset <number>` - Add offset to all exposed ports
+- `--verbose` - Explain why each overlay was included in the resolved plan
 - `--json` - Output as JSON
 
 ### Port Offset Example
@@ -308,6 +317,35 @@ Auto-Added Dependencies:
   + prometheus (Prometheus)
 ```
 
+### Verbose Dependency Narration
+
+Add `--verbose` when you want the plan to explain why each overlay appears in the final result:
+
+```bash
+npx container-superposition plan --stack compose --overlays grafana --verbose
+```
+
+**Additional output:**
+
+```text
+Dependency Resolution:
+  grafana (Grafana)
+    - selected directly by the user
+  prometheus (Prometheus)
+    - required by grafana
+    - path: grafana -> prometheus
+```
+
+This keeps the standard summary intact and adds the reasoning behind direct selections, auto-added dependencies, and failure notes when resolution cannot complete cleanly.
+
+The same verbose explanation works for existing manifests:
+
+```bash
+npx container-superposition plan --from-manifest .devcontainer/superposition.json --verbose
+```
+
+In manifest mode, overlays loaded from `superposition.json` are treated as the explicit root set and auto-added dependencies are still explained separately.
+
 ### Conflict Detection
 
 The `plan` command detects conflicts before generation:
@@ -334,6 +372,12 @@ npx container-superposition plan --stack compose --overlays docker-in-docker,doc
 ```bash
 # Get plan as JSON
 npx container-superposition plan --stack compose --overlays postgres --json
+
+# Include structured dependency explanations
+npx container-superposition plan --stack compose --overlays grafana --json --verbose
+
+# Include structured dependency explanations from a manifest
+npx container-superposition plan --from-manifest .devcontainer/superposition.json --json --verbose
 ```
 
 **Example output:**
@@ -357,11 +401,19 @@ npx container-superposition plan --stack compose --overlays postgres --json
         ".devcontainer/docker-compose.yml",
         ".devcontainer/.env.example",
         ".devcontainer/README.md"
-    ],
-    "portOffset": 0
+    ]
 }
 ```
 
+When `--verbose` is also present, the JSON output includes a `verbose` object with:
+
+- one entry per included overlay
+- direct-vs-dependency selection type
+- input mode metadata for overlay-list vs manifest planning
+- parent reasons for inclusion
+- ordered dependency paths for transitive inclusions
+- resolution notes for skipped overlays or conflicts
+
 ## Scripting Examples
 
 ### Export All Overlays to JSON

package/docs/examples.md

@@ -10,6 +10,37 @@ npm run init
 
 Follow the prompts to select your stack, database, tools, and output location.
 
+## Declarative Project Config
+
+```yaml
+stack: compose
+language:
+    - nodejs
+database:
+    - postgres
+outputPath: ./.devcontainer
+customizations:
+    environment:
+        APP_ENV: development
+    devcontainerPatch:
+        features:
+            ghcr.io/devcontainers-extra/features/apt-get-packages:1:
+                packages: jq
+```
+
+```bash
+npm run init -- --no-interactive
+```
+
+Creates the same generated output you would get from equivalent clean-generation
+input, while keeping the setup intent in version control.
+
+```bash
+npm run init -- regen
+```
+
+Regenerates from the repository project file by default when one exists.
+
 ## Non-Interactive Examples
 
 ### .NET with PostgreSQL
@@ -411,11 +442,14 @@ npm run init -- --from-manifest ./superposition.json
 
 ### Non-Interactive Regeneration
 
-Regenerate exact same setup (useful for updating to latest overlay versions):
+Use `regen` when you want deterministic replay of a persisted source:
 
 ```bash
-# Regenerate with exact same selections, skip confirmation, no backup
-npm run init -- --from-manifest ./superposition.json --yes --no-backup
+# Regenerate with exact same selections from a manifest, no backup
+npm run init -- regen --from-manifest ./superposition.json --no-backup
+
+# Or let regen use the repository project file when present
+npm run init -- regen
 ```
 
 **Use cases:**
@@ -463,7 +497,7 @@ git push
 # Developer 2: Clone and regenerate from manifest
 git clone <repo>
 npm install
-npm run init -- --from-manifest ./superposition.json --yes
+npm run init -- regen --from-manifest ./superposition.json
 # Gets exact same devcontainer setup
 ```
 
@@ -481,7 +515,7 @@ The manifest stores and restores:
 
 ```json
 {
-    "version": "0.1.0",
+    "version": "X.Y.Z",
     "generated": "2026-02-08T10:00:00Z",
     "baseTemplate": "compose",
     "baseImage": "bookworm",
@@ -572,5 +606,5 @@ mv prod/superposition.json prod-superposition.json
 
 # Now you have three manifests for different environments
 # Regenerate any environment from its manifest
-npm run init -- --from-manifest ./dev-superposition.json --yes --output ./dev
+npm run init -- regen --from-manifest ./dev-superposition.json --output ./dev
 ```

package/docs/filesystem-contract.md

@@ -0,0 +1,58 @@
+# Filesystem Contract
+
+This describes what the tool writes and which files are safe to edit.
+
+## What Gets Written
+
+```
+your-project/
+├── .devcontainer/               # Main devcontainer directory
+│   ├── devcontainer.json        # Container configuration
+│   ├── docker-compose.yml       # Services (compose stack only)
+│   ├── .env.example             # Environment variable templates
+│   ├── ports.json               # Port documentation and connection strings
+│   ├── scripts/                 # Setup and verification scripts
+│   │   ├── post-create.sh       # Runs once when container is created
+│   │   └── post-start.sh        # Runs every time container starts
+│   └── custom/                  # Your customizations (preserved across regen)
+│       ├── devcontainer.patch.json
+│       └── docker-compose.patch.yml
+├── superposition.json           # Manifest file (enables regeneration)
+└── .devcontainer.backup-*/      # Automatic backups (gitignored)
+```
+
+## Files You Should Customize
+
+- `.devcontainer/.env` or `.env` (copied from `.env.example`)
+- `.devcontainer/custom/` (your patches and scripts)
+
+## Files Safe to Edit Directly
+
+- `.devcontainer/custom/devcontainer.patch.json`
+- `.devcontainer/custom/docker-compose.patch.yml`
+- `.devcontainer/custom/environment.env`
+- `.devcontainer/custom/scripts/*`
+
+## Files Regenerated (Do Not Edit Directly)
+
+- `.devcontainer/devcontainer.json`
+- `.devcontainer/docker-compose.yml`
+- `.devcontainer/scripts/*`
+
+## Files You Should Commit
+
+- `superposition.json`
+- `.devcontainer/` (generated configuration)
+- `.devcontainer/custom/` (project-specific patches)
+- `.devcontainer/.env.example`
+
+## Files in .gitignore
+
+```
+# Environment secrets (never commit)
+.env
+.devcontainer/.env
+
+# Regeneration backups (local only)
+.devcontainer.backup-*
+```