container-superposition 0.1.3 → 0.1.5

package/dist/tool/utils/summary.js

@@ -0,0 +1,260 @@
+/**
+ * Summary utilities for post-generation output
+ */
+import chalk from 'chalk';
+import boxen from 'boxen';
+import { generateUrl } from './port-utils.js';
+/**
+ * Detect warnings based on selected overlays and configuration
+ */
+export function detectWarnings(overlays, answers) {
+    const warnings = [];
+    // Check for docker-sock security warning
+    const hasDockerSock = overlays.some((o) => o.id === 'docker-sock');
+    if (hasDockerSock) {
+        warnings.push('docker-sock overlay provides root access to host Docker daemon\n  Use only for trusted code. Consider docker-in-docker for isolation.');
+    }
+    // Check for target mismatch
+    const target = answers.target || 'local';
+    if (hasDockerSock && target === 'codespaces') {
+        warnings.push('docker-sock may not work in GitHub Codespaces\n  Consider using docker-in-docker instead.');
+    }
+    // Check for high port count
+    const portCount = overlays.reduce((count, o) => count + (o.ports?.length || 0), 0);
+    const hasHighPortCountWarning = portCount > 10;
+    if (hasHighPortCountWarning) {
+        warnings.push(`High port count (${portCount} ports) may cause conflicts\n  Consider using --port-offset to avoid conflicts with other projects.`);
+    }
+    // Check for no port offset with multiple services
+    const hasServices = overlays.some((o) => o.category === 'database' || o.category === 'observability');
+    if (!hasHighPortCountWarning &&
+        hasServices &&
+        (!answers.portOffset || answers.portOffset === 0)) {
+        warnings.push('Running multiple devcontainers simultaneously may cause port conflicts\n  Use --port-offset 100 (or higher) to avoid conflicts.');
+    }
+    return warnings;
+}
+/**
+ * Generate helpful tips based on configuration
+ */
+export function generateTips(overlays, answers) {
+    const tips = [];
+    // Suggest committing manifest
+    if (!answers.preset) {
+        tips.push('Commit superposition.json to enable team regeneration');
+    }
+    // Suggest customization directory
+    const hasCustomDir = overlays.length > 3;
+    if (hasCustomDir) {
+        tips.push('Preserve customizations in .devcontainer/custom/');
+    }
+    // Suggest regen command
+    tips.push('Regenerate anytime: npx container-superposition regen');
+    return tips;
+}
+/**
+ * Generate next steps based on mode
+ */
+export function generateNextSteps(isManifestOnly, isRegen) {
+    if (isManifestOnly) {
+        return [
+            'Review the generated superposition.json file',
+            'Commit it to your repository',
+            'Team members can run "npx container-superposition regen"',
+        ];
+    }
+    if (isRegen) {
+        return [
+            'Rebuild container:\n     Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P) → "Dev Containers: Rebuild Container"',
+            'Test changes manually',
+            'Review any customizations in .devcontainer/custom/',
+        ];
+    }
+    return [
+        'Customize environment:\n     cp .devcontainer/.env.example .devcontainer/.env',
+        'Open in VS Code:\n     code .',
+        'Reopen in Container:\n     Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P) → "Dev Containers: Reopen in Container"',
+        'Verify setup:\n     npx container-superposition doctor',
+    ];
+}
+/**
+ * Convert overlay metadata to service info
+ */
+export function overlaysToServices(overlays) {
+    return overlays.map((overlay) => {
+        // Extract version from name if present (e.g., "PostgreSQL 16" -> version: "16")
+        const versionMatch = overlay.name.match(/\d+(?:\.\d+)?/);
+        const version = versionMatch ? versionMatch[0] : undefined;
+        return {
+            name: overlay.name,
+            category: overlay.category,
+            version,
+        };
+    });
+}
+/**
+ * Convert normalized ports to port info with URLs
+ */
+export function portsToPortInfo(ports, connectionStrings) {
+    return ports.map((port) => {
+        const service = port.service || 'unknown';
+        const url = generateUrl(port);
+        // Try to find connection string for this service
+        let connectionString;
+        if (connectionStrings[service]) {
+            connectionString = connectionStrings[service];
+        }
+        else if (connectionStrings[`${service}-url`]) {
+            connectionString = connectionStrings[`${service}-url`];
+        }
+        return {
+            service,
+            port: port.port,
+            actualPort: port.actualPort,
+            url,
+            connectionString,
+        };
+    });
+}
+/**
+ * Format and print generation summary.
+ *
+ * @param summary The generation summary to render.
+ * @param quiet   When true, suppresses all console output. This parameter is
+ *                reserved for callers (for example, CLI commands or tests)
+ *                that need to generate a summary object but handle user
+ *                messaging themselves.
+ */
+export function printSummary(summary, quiet = false) {
+    // If quiet mode is enabled, skip printing while still allowing callers
+    // to invoke this function consistently. See the JSDoc for intended usage.
+    if (quiet) {
+        return;
+    }
+    const lines = [];
+    // Header
+    const title = summary.isManifestOnly
+        ? '📋 Manifest Generated'
+        : summary.backupPath
+            ? '🔄 DevContainer Regenerated'
+            : '✨ DevContainer Generated';
+    lines.push(chalk.bold.green(title));
+    lines.push('');
+    // Backup notification (for regen)
+    if (summary.backupPath) {
+        lines.push(chalk.yellow(`Backup created: ${summary.backupPath}`));
+        lines.push('');
+    }
+    // Files created (manifest-only shows just manifest)
+    if (summary.isManifestOnly) {
+        lines.push(chalk.white('Manifest:'));
+        lines.push(chalk.gray(`  ${summary.manifestPath || 'superposition.json'}`));
+        lines.push('');
+    }
+    else {
+        lines.push(chalk.white('Files created:'));
+        for (const file of summary.files.slice(0, 8)) {
+            lines.push(chalk.gray(`  ${file}`));
+        }
+        if (summary.files.length > 8) {
+            lines.push(chalk.gray(`  ... and ${summary.files.length - 8} more`));
+        }
+        lines.push('');
+    }
+    // Services included
+    if (summary.services.length > 0) {
+        lines.push(chalk.white('Services included:'));
+        const displayServices = summary.services.slice(0, 10);
+        for (const service of displayServices) {
+            const versionStr = service.version ? ` ${service.version}` : '';
+            const categoryStr = chalk.dim(` (${service.category})`);
+            lines.push(chalk.green(`  ✓ ${service.name}${versionStr}`) + categoryStr);
+        }
+        if (summary.services.length > 10) {
+            lines.push(chalk.gray(`  ... and ${summary.services.length - 10} more`));
+        }
+        lines.push('');
+    }
+    // Port mappings and service URLs
+    if (summary.ports.length > 0) {
+        lines.push(chalk.white('🌐 Service Access'));
+        lines.push('');
+        // Group by HTTP services and database services
+        const httpPorts = summary.ports.filter((p) => p.url);
+        const dbPorts = summary.ports.filter((p) => p.connectionString && !p.url);
+        // Show application/HTTP services first
+        if (httpPorts.length > 0) {
+            for (const port of httpPorts) {
+                const label = port.service.charAt(0).toUpperCase() + port.service.slice(1);
+                lines.push(chalk.cyan(`  ${label}:`));
+                lines.push(chalk.gray(`    ${port.url}`));
+            }
+            lines.push('');
+        }
+        // Show database/infrastructure services
+        if (dbPorts.length > 0) {
+            lines.push(chalk.white('  Infrastructure:'));
+            for (const port of dbPorts) {
+                const label = port.service.charAt(0).toUpperCase() + port.service.slice(1);
+                lines.push(chalk.cyan(`    ${label}:`));
+                lines.push(chalk.gray(`      ${port.connectionString}`));
+            }
+            lines.push('');
+        }
+        // Port offset info
+        if (summary.portOffset > 0) {
+            lines.push(chalk.dim(`  Port offset: ${summary.portOffset}`));
+        }
+        else {
+            lines.push(chalk.dim('  Port offset: 0 (use --port-offset to avoid conflicts)'));
+        }
+        lines.push('');
+    }
+    // Warnings
+    if (summary.warnings.length > 0) {
+        lines.push(chalk.yellow('⚠️  Warnings'));
+        lines.push('');
+        for (const warning of summary.warnings) {
+            const warningLines = warning.split('\n');
+            lines.push(chalk.yellow(`  • ${warningLines[0]}`));
+            for (let i = 1; i < warningLines.length; i++) {
+                lines.push(chalk.dim(`    ${warningLines[i]}`));
+            }
+        }
+        lines.push('');
+    }
+    // Tips
+    if (summary.tips.length > 0) {
+        lines.push(chalk.cyan('💡 Tips'));
+        lines.push('');
+        for (const tip of summary.tips) {
+            lines.push(chalk.gray(`  • ${tip}`));
+        }
+        lines.push('');
+    }
+    // Next steps
+    lines.push(chalk.white('📝 Next Steps'));
+    lines.push('');
+    for (let i = 0; i < summary.nextSteps.length; i++) {
+        const step = summary.nextSteps[i];
+        const stepLines = step.split('\n');
+        lines.push(chalk.gray(`  ${i + 1}. ${stepLines[0]}`));
+        for (let j = 1; j < stepLines.length; j++) {
+            lines.push(chalk.dim(`     ${stepLines[j]}`));
+        }
+    }
+    // Footer
+    if (!summary.isManifestOnly) {
+        lines.push('');
+        lines.push(chalk.dim(`Generated in .devcontainer/ • Manifest: ${summary.manifestPath || 'superposition.json'}`));
+    }
+    // Print with boxen
+    console.log('\n' +
+        boxen(lines.join('\n'), {
+            padding: 1,
+            borderColor: 'green',
+            borderStyle: 'round',
+            margin: 1,
+        }));
+}
+//# sourceMappingURL=summary.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"summary.js","sourceRoot":"","sources":["../../../tool/utils/summary.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,196 @@
+# 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. **`.devcontainer/custom/devcontainer.patch.json`** — any config that has no overlay equivalent (custom features, extensions, mounts, remoteEnv, etc.)
+3. **`.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
+
+# 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                                             |
+| `--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 `custom/` patches** — inspect what was preserved and trim anything no longer needed.
+3. **Regenerate** — rebuild your `.devcontainer/` from the manifest:
+    ```bash
+    npx container-superposition regen
+    ```
+4. **Commit `superposition.json`** 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