groundwork-method 0.0.1 → 0.11.0

package/dist/src/generators/python-microservice/generator.js

@@ -0,0 +1,265 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = default_1;
+const devkit_1 = require("@nx/devkit");
+const path = __importStar(require("path"));
+const provenance_1 = require("../shared/provenance");
+const scaffold_helpers_1 = require("../shared/scaffold-helpers");
+const capabilities_1 = require("../shared/capabilities");
+async function default_1(tree, options) {
+    const serviceNames = (0, devkit_1.names)(options.name);
+    const projectRoot = `services/${serviceNames.fileName}`;
+    // src-layout: the importable package is `src/<packageName>` (PEP src-layout),
+    // so the package name is the service name in snake_case (a valid Python
+    // identifier). It names the `src/__packageName__/` template dir, every
+    // `from <pkg>.…` import, the hatch wheel package, and the import-linter root.
+    // Derive it from the kebab fileName (hyphens → underscores), NOT constantName:
+    // nx's constantName collapses single-char segments (`a-b1` → `AB1`), which would
+    // make the package name diverge from the intuitive `a_b1` a developer expects.
+    const packageName = serviceNames.fileName.replace(/-/g, '_');
+    let assignedPort = 8000;
+    let composeDoc = null;
+    if (tree.exists('docker-compose.yml')) {
+        try {
+            const yaml = require('yaml');
+            const composeContent = tree.read('docker-compose.yml', 'utf-8');
+            composeDoc = yaml.parseDocument(composeContent);
+            const usedPorts = new Set();
+            // Collect ports from docker-compose.yml
+            const servicesMap = composeDoc.get('services');
+            if (servicesMap && servicesMap.items) {
+                for (const item of servicesMap.items) {
+                    const service = item.value;
+                    if (service && service.get) {
+                        const ports = service.get('ports');
+                        if (ports && ports.items) {
+                            for (const pItem of ports.items) {
+                                const portStr = String(pItem.value || pItem);
+                                const match = portStr.match(/^(\d+):/);
+                                if (match) {
+                                    usedPorts.add(parseInt(match[1], 10));
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            // Also collect ports from .env files of natively-run services (not in docker-compose)
+            if (tree.exists('services')) {
+                for (const svcName of tree.children('services') ?? []) {
+                    const envPath = `services/${svcName}/.env`;
+                    if (tree.exists(envPath)) {
+                        const envContent = tree.read(envPath, 'utf-8') ?? '';
+                        for (const line of envContent.split('\n')) {
+                            const m = line.match(/^(?:PORT|SERVER_PORT)=(\d+)/);
+                            if (m)
+                                usedPorts.add(parseInt(m[1], 10));
+                        }
+                    }
+                }
+            }
+            while (usedPorts.has(assignedPort)) {
+                assignedPort++;
+            }
+        }
+        catch (e) {
+            console.warn('Failed to parse docker-compose.yml for port calculation:', e);
+        }
+    }
+    // Default the provider so programmatic callers (e.g. tests) that omit it get
+    // today's OpenAI behaviour unchanged. Only consumed inside `--llm` templates.
+    const llmProvider = options.llmProvider ?? 'openai';
+    const templateOptions = {
+        ...options,
+        ...serviceNames,
+        packageName,
+        assignedPort,
+        llmProvider,
+        tmpl: '' // required by generateFiles
+    };
+    (0, devkit_1.generateFiles)(tree, path.join(__dirname, '..', '..', '..', '..', 'src', 'generators', 'python-microservice', 'files'), projectRoot, templateOptions);
+    (0, scaffold_helpers_1.deployStackDocs)(tree, path.join(__dirname, '..', '..', '..', '..', 'src', 'generators', 'python-microservice', 'docs'));
+    // Auto-inject into docker-compose.yml if it exists
+    if (composeDoc) {
+        try {
+            if (!composeDoc.get('services')) {
+                // createNode so the result is a YAMLMap with .has/.set (a plain {} is not).
+                composeDoc.set('services', composeDoc.createNode({}));
+            }
+            const servicesMap = composeDoc.get('services');
+            // Only wire the infrastructure this service actually uses. Redis is needed
+            // for the WebSocket backplane or Redis pub/sub; the Pub/Sub emulator only
+            // for GCP Pub/Sub messaging. A plain --rest --postgres --llm service
+            // provisions neither.
+            const usesRedis = options.websockets || options.messaging === 'redis';
+            const usesPubSub = options.messaging === 'gcp-pubsub';
+            if (!options.native && !servicesMap.has(serviceNames.fileName)) {
+                const environment = [`SERVER_PORT=${assignedPort}`];
+                if (options.postgres) {
+                    environment.push('DB_HOST=db', 'DB_PORT=5432', 'DB_USER=${DB_USER:-postgres}', 'DB_PASSWORD=${DB_PASSWORD:-postgres}', `DB_NAME=\${DB_NAME:-${serviceNames.fileName}}`);
+                }
+                if (usesRedis) {
+                    environment.push('REDIS_URL=redis:6379');
+                }
+                if (usesPubSub) {
+                    environment.push('PUBSUB_EMULATOR_HOST=pubsub:${PUBSUB_PORT:-8085}');
+                }
+                environment.push('OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4317', 'OTEL_EXPORTER_OTLP_PROTOCOL=grpc');
+                const dependsOn = {};
+                if (options.postgres) {
+                    dependsOn.db = { condition: 'service_healthy' };
+                }
+                if (usesRedis) {
+                    dependsOn.redis = { condition: 'service_healthy' };
+                }
+                const newService = {
+                    build: {
+                        context: `./${projectRoot}`,
+                        dockerfile: 'Dockerfile'
+                    },
+                    container_name: serviceNames.fileName,
+                    restart: 'unless-stopped',
+                    ports: [
+                        `${assignedPort}:${assignedPort}`
+                    ],
+                    environment
+                };
+                // Only the REST entrypoint serves /healthz; the runpod worker image
+                // runs a background worker with no HTTP server, so it gets no probe.
+                if (options.rest && !options.runpod) {
+                    // The python:slim runtime image has no curl, so probe the health
+                    // endpoint with the interpreter that is guaranteed to be present.
+                    newService.healthcheck = {
+                        test: [
+                            'CMD-SHELL',
+                            `python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://localhost:${assignedPort}/healthz').status==200 else 1)"`
+                        ],
+                        interval: '10s',
+                        timeout: '5s',
+                        retries: 5,
+                        start_period: '20s'
+                    };
+                }
+                if (Object.keys(dependsOn).length > 0) {
+                    newService.depends_on = dependsOn;
+                }
+                newService.networks = ['groundwork-net'];
+                servicesMap.set(serviceNames.fileName, newService);
+                // db only when this service uses Postgres; jaeger always for a
+                // containerized service (it exports OTLP). Neither is in the base compose.
+                (0, scaffold_helpers_1.ensureOptionalInfra)(composeDoc, servicesMap, {
+                    usesRedis,
+                    usesPubSub,
+                    usesDb: !!options.postgres,
+                    usesTelemetry: true,
+                    projectPrefix: (0, scaffold_helpers_1.readProjectPrefix)(tree),
+                });
+                tree.write('docker-compose.yml', composeDoc.toString());
+            }
+            else if (options.native && (options.postgres || usesRedis || usesPubSub)) {
+                // Native sidecar: no app container in compose, but provision the backing
+                // infra it connects to. A host process gets no forced tracing backend —
+                // telemetry is wired only if the project explicitly runs jaeger.
+                (0, scaffold_helpers_1.ensureOptionalInfra)(composeDoc, servicesMap, {
+                    usesRedis,
+                    usesPubSub,
+                    usesDb: !!options.postgres,
+                    usesTelemetry: false,
+                    projectPrefix: (0, scaffold_helpers_1.readProjectPrefix)(tree),
+                });
+                tree.write('docker-compose.yml', composeDoc.toString());
+            }
+        }
+        catch (e) {
+            console.warn('Failed to update docker-compose.yml:', e);
+        }
+    }
+    // Native mode: the service runs as a host process (e.g. it needs Metal/MPS that
+    // Docker on macOS can't provide), so register it as a sidecar runner instead of
+    // a compose service. `./dev start` launches it via `uv run`.
+    if (options.native) {
+        (0, scaffold_helpers_1.registerRunner)(tree, {
+            name: serviceNames.fileName,
+            kind: 'sidecar',
+            cmd: `uv run python -m ${packageName}.main`,
+            cwd: projectRoot,
+            autostart: true,
+        });
+    }
+    const pkgRoot = `${projectRoot}/src/${packageName}`;
+    if (!options.rest) {
+        tree.delete(`${pkgRoot}/entrypoints/api`);
+        // Middleware tests import the API entrypoint, which only exists with --rest.
+        tree.delete(`${projectRoot}/tests/test_middleware.py`);
+    }
+    if (!options.postgres) {
+        tree.delete(`${pkgRoot}/adapters/database.py`);
+        tree.delete(`${pkgRoot}/adapters/repository.py`);
+        // Schema lives in db/ (parity with Go); migrate runs scripts/apply-schema.sh.
+        tree.delete(`${projectRoot}/db`);
+        tree.delete(`${projectRoot}/scripts/apply-schema.sh`);
+    }
+    if (!options.websockets) {
+        tree.delete(`${pkgRoot}/entrypoints/api/websocket_handler.py`);
+        tree.delete(`${pkgRoot}/adapters/websocket_hub.py`);
+    }
+    if (options.messaging === 'none') {
+        tree.delete(`${pkgRoot}/adapters/message_queue.py`);
+    }
+    if (!options.runpod) {
+        tree.delete(`${pkgRoot}/entrypoints/worker`);
+        tree.delete(`${pkgRoot}/adapters/comfyui.py`);
+        // Worker test imports the runpod worker handler, deleted above.
+        tree.delete(`${projectRoot}/tests/test_worker.py`);
+    }
+    // LLM is a composable capability port (plan WS-F). The chosen provider —
+    // anthropic | openai | local | none — selects the adapter; the port, the
+    // contract test, the provider dependency and its env footprint all come from
+    // the capability registry via one shared injector (no inline per-provider
+    // template here). `none` ships the bare port: the interface + a stub + a red bet.
+    if (options.llm) {
+        (0, capabilities_1.applyCapability)(tree, {
+            capability: 'llm',
+            provider: llmProvider,
+            stack: 'python',
+            serviceRoot: projectRoot,
+        });
+    }
+    (0, scaffold_helpers_1.promoteEngineerSkill)(tree, 'groundwork-python-engineer');
+    await (0, devkit_1.formatFiles)(tree);
+    (0, provenance_1.recordGeneratorProvenance)(tree, 'python-microservice', options);
+}
+//# sourceMappingURL=generator.js.map

package/dist/src/generators/python-microservice/generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.js","sourceRoot":"","sources":["../../../../src/generators/python-microservice/generator.ts"],"names":[],"mappings":"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"}

package/dist/src/generators/shared/brand-tokens.d.ts

@@ -0,0 +1,89 @@
+import { Tree } from '@nx/devkit';
+/**
+ * Shared brand-token projection.
+ *
+ * `resolveVisual(tree)` reads `.groundwork/config/brand-tokens.json` and resolves
+ * the per-app palette + atmosphere layer into a single `ResolvedVisual` shape that
+ * surface generators project onto their own theming model:
+ *   - `nextjs-app` → Tailwind-v4/shadcn `app/brand.css` (`renderBrandCss`, kept in
+ *     that generator because the variable names + utilities are shadcn-specific).
+ *   - `docs-site` → Fumadocs `--fd-*` theme variables (`renderDocsBrandCss`).
+ *
+ * The resolver itself is theme-system-agnostic: it validates and normalises the
+ * token values, falling back to a neutral starter so generation always emits valid
+ * CSS even when no brand-tokens.json exists or the file is malformed.
+ */
+export declare const BRAND_TOKENS_PATH = ".groundwork/config/brand-tokens.json";
+/** shadcn structural CSS variables with their neutral defaults (light/dark) —
+ *  the palette app/globals.css carried before brand projection. The generator
+ *  overrides the brand-mappable subset from brand-tokens.json's visual block;
+ *  the rest stay these tuned neutrals so component contrast stays safe. */
+export declare const SHADCN_VARS: Record<string, {
+    light: string;
+    dark: string;
+}>;
+/** Which shadcn vars each visual.palette role drives. Only the contrast-safe
+ *  slots are mapped: a surface role onto surfaces, the text role onto
+ *  foregrounds, brand hues onto primary/ring/charts. Contrast-sensitive
+ *  foregrounds-on-colour keep their tuned neutral defaults. */
+export declare const PALETTE_TO_SHADCN: Record<string, string[]>;
+export type LD = {
+    light: string;
+    dark: string;
+};
+/** CSS colour — hex (3/4/6/8) or OKLCH with optional alpha. */
+export declare function validColor(value: unknown): string | null;
+/** CSS length: px/rem/em/% or a bare number treated as px. */
+export declare function validLen(value: unknown): string | null;
+/** A guarded passthrough for composite CSS values (shadow stacks, gradients,
+ *  transforms, easing). Rejects anything that could break out of a declaration
+ *  so a malformed token degrades to the neutral default instead of corrupting
+ *  the stylesheet. */
+export declare function safeCss(value: unknown, maxLen?: number): string | null;
+/** Compose an elevation layer array into a box-shadow string (x is always 0).
+ *  Returns null if any layer is malformed, so the level falls back to neutral. */
+export declare function composeShadow(layers: unknown): string | null;
+export declare const NEUTRAL_BLUR: {
+    subtle: string;
+    standard: string;
+    heavy: string;
+};
+export declare const NEUTRAL_SHADOW: Record<'low' | 'mid' | 'high', LD>;
+export declare const NEUTRAL_SURFACE: Record<'glass' | 'elevated' | 'hero', {
+    tint: LD;
+    border: LD;
+}>;
+export declare const NEUTRAL_TYPE_ROLES: Record<string, {
+    size: string;
+    line: string;
+    weight: string;
+    tracking: string;
+}>;
+export declare const NEUTRAL_MOTION: Record<string, {
+    duration: string;
+    ease: string;
+    transform: string;
+}>;
+export interface ResolvedVisual {
+    shadcn: Record<string, LD>;
+    radius: string;
+    blur: {
+        subtle: string;
+        standard: string;
+        heavy: string;
+    };
+    shadow: Record<'low' | 'mid' | 'high', LD>;
+    gradientHero: LD;
+    surfaces: Record<'glass' | 'elevated' | 'hero', {
+        tint: LD;
+        border: LD;
+    }>;
+    typeRoles: typeof NEUTRAL_TYPE_ROLES;
+    motion: typeof NEUTRAL_MOTION;
+    source: 'visual-block' | 'identity-only' | 'default';
+}
+/** Read brand-tokens.json and resolve the per-app palette + atmosphere layer.
+ *  Mirrors electron-app/flutter-app token handling: a visual block projects in
+ *  full; Tier-1-only seeds the brand hue from identity; absent/malformed tokens
+ *  fall back to the neutral starter so generation always emits valid CSS. */
+export declare function resolveVisual(tree: Tree): ResolvedVisual;