@aid-framework/generator-sdk 0.1.58 → 0.1.59

package/dist/scaffold.js

@@ -0,0 +1,248 @@
+/**
+ * Scaffold content: generator-authored files that live outside the managed roots (§6a).
+ *
+ * Today that is the repository's own CI. It is planned like any other file, but it is
+ * written once and then belongs to the developer: `aid gen` never overwrites it, never
+ * records it in the manifest, and `aid eject` reports it as already owned. That split is
+ * what makes a generated workflow usable -- CI has to be edited for a runner, a
+ * credential, or a second toolchain, and every one of those edits would otherwise be a
+ * drift conflict against a file the developer is supposed to own.
+ *
+ * The emitted workflow deliberately contains **no** `apply` step and no cloud keys: it
+ * gates the repository and stops there. Deployment stays a human action, per §12.6.
+ */
+/** The repository CI: the spec gates, then lint/build/test for the app tier. */
+export const CI_WORKFLOW_PATH = '.github/workflows/ci.yml';
+/**
+ * The eval gate. A separate workflow because it needs a model credential and therefore
+ * cannot be a required check on a fork pull request: it runs on `workflow_dispatch` and
+ * nightly, and reports a skip -- not a pass -- when the credential is absent.
+ */
+export const EVALS_WORKFLOW_PATH = '.github/workflows/evals.yml';
+/**
+ * Action pins. A tag is mutable; a SHA is not, and a generated workflow that runs
+ * `@v4` is one force-push away from running different code than it did last week.
+ * These are the commits the `v4`/`v5` tags resolved to when this was written.
+ */
+export const ACTION_PINS = {
+    checkout: 'actions/checkout@11d5960a326750d5838078e36cf38b85af677262',
+    setupNode: 'actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020',
+    setupPython: 'actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065',
+};
+/** `major.minor` of a semver string, used to pin the CLI a workflow installs. */
+export function cliRangeFor(version) {
+    const match = /^(\d+)\.(\d+)\./.exec(version);
+    return match === null ? version : `${match[1]}.${match[2]}`;
+}
+function lines(values, indent = '          ') {
+    return values.map((value) => `${indent}${value}`);
+}
+/**
+ * The CI workflow for a generated project.
+ *
+ * The spec gates are the framework's own contract and always run. The app job needs the
+ * project's dependency manifest, and a job-level `if` cannot call `hashFiles`, so a small
+ * `detect` job probes for the file and the app job is skipped -- not green -- without it.
+ * The infra job is skipped the same way when `infra/` is absent, and it only compares the
+ * committed tree against the spec: `plan`/`apply` need credentials and stay human actions.
+ */
+export function scaffoldCi(profile, cliRange) {
+    const content = [
+        `# Generated once by \`aid gen\` for the \`${profile.target}\` target, then yours.`,
+        '# A scaffold file is never overwritten and never recorded in aid.manifest.json,',
+        '# so edit it freely: a new runner, a cache, an extra toolchain.',
+        'name: CI',
+        '',
+        'on:',
+        '  push:',
+        '    branches: [main]',
+        '  pull_request:',
+        '',
+        'concurrency:',
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: a GitHub Actions expression, emitted literally.
+        '  group: ci-${{ github.workflow }}-${{ github.ref }}',
+        '  cancel-in-progress: true',
+        '',
+        'permissions:',
+        '  contents: read',
+        '',
+        'jobs:',
+        '  spec:',
+        '    name: Spec gates',
+        '    runs-on: ubuntu-latest',
+        '    timeout-minutes: 15',
+        '    steps:',
+        `      - uses: ${ACTION_PINS.checkout}`,
+        `      - uses: ${ACTION_PINS.setupNode}`,
+        '        with:',
+        "          node-version: '22'",
+        '      - name: Install the AID CLI',
+        `        run: npm install --global @aid-framework/cli@${cliRange}`,
+        '      - name: Validate the spec',
+        `        run: aid validate ${profile.specPath}`,
+        '      - name: The committed tree matches the spec',
+        `        run: aid gen ${profile.specPath} --check`,
+        '      - name: Diagnose the tree',
+        `        run: aid doctor ${profile.specPath}`,
+        '',
+        '  detect:',
+        '    name: Detect the app',
+        '    runs-on: ubuntu-latest',
+        '    outputs:',
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: a GitHub Actions expression, emitted literally.
+        '      has_app: ${{ steps.probe.outputs.has_app }}',
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: a GitHub Actions expression, emitted literally.
+        '      has_infra: ${{ steps.infra.outputs.has_infra }}',
+        '    steps:',
+        `      - uses: ${ACTION_PINS.checkout}`,
+        '      - id: probe',
+        '        run: |',
+        `          if [ -f ${profile.dependencyManifest} ]; then`,
+        '            echo "has_app=true" >> "$GITHUB_OUTPUT"',
+        '          else',
+        '            echo "has_app=false" >> "$GITHUB_OUTPUT"',
+        '          fi',
+        '      - id: infra',
+        '        run: |',
+        '          if [ -d infra ]; then',
+        '            echo "has_infra=true" >> "$GITHUB_OUTPUT"',
+        '          else',
+        '            echo "has_infra=false" >> "$GITHUB_OUTPUT"',
+        '          fi',
+        '',
+        '  app:',
+        '    name: Lint, build, and test',
+        '    runs-on: ubuntu-latest',
+        '    timeout-minutes: 20',
+        '    needs: detect',
+        `    # Skipped, not green: without ${profile.dependencyManifest} there is nothing to`,
+        `    # build, and a passing check that never ran is worse than an explicit skip.`,
+        `    if: needs.detect.outputs.has_app == 'true'`,
+        '    steps:',
+        `      - uses: ${ACTION_PINS.checkout}`,
+        ...lines(profile.toolchain, '      '),
+        '      - name: Install dependencies',
+        '        run: |',
+        ...lines(profile.install, '          '),
+        '      - name: Lint',
+        '        run: |',
+        ...lines(profile.lint, '          '),
+        '      - name: Build',
+        `        run: ${profile.build}`,
+        '      - name: Test',
+        `        run: ${profile.test}`,
+        '',
+        '  infra:',
+        '    name: Infra matches the spec',
+        '    runs-on: ubuntu-latest',
+        '    timeout-minutes: 15',
+        '    needs: detect',
+        '    # Skipped, not green: a project that has not generated infra/ has no committed',
+        '    # tree to compare, and this job never plans against a cloud account.',
+        `    if: needs.detect.outputs.has_infra == 'true'`,
+        '    steps:',
+        `      - uses: ${ACTION_PINS.checkout}`,
+        `      - uses: ${ACTION_PINS.setupNode}`,
+        '        with:',
+        "          node-version: '22'",
+        '      - name: Install the AID CLI',
+        `        run: npm install --global @aid-framework/cli@${cliRange}`,
+        '      - name: The committed infra tree matches the spec',
+        `        run: aid infra gen ${profile.specPath} --check`,
+        '',
+    ].join('\n');
+    return { path: CI_WORKFLOW_PATH, content, owner: 'scaffold' };
+}
+/**
+ * The eval gate for a project whose spec declares `gate.ci: true` evals.
+ *
+ * It never runs on `pull_request`. The generated evals measure a real model: with no
+ * credential the gateway falls back to the fake provider, whose output does not satisfy
+ * the eval's JSON schema, and the gate fails. Requiring the key on PRs would therefore
+ * either leak a secret to forks or turn the gate red for every contributor, so the gate
+ * runs on `workflow_dispatch` and nightly instead, and a missing key is an **error**
+ * rather than a silent skip: a gate that is green because it never ran is the failure
+ * mode this whole tier exists to avoid.
+ */
+export function scaffoldEvals(profile) {
+    const guarded = profile.secrets.length > 0;
+    const credentialSteps = guarded
+        ? [
+            '      - name: Check the model credential',
+            '        id: creds',
+            '        env:',
+            ...profile.secrets.map((name) => `          ${name}: \${{ secrets.${name} }}`),
+            '        run: |',
+            '          missing=0',
+            ...profile.secrets.flatMap((name) => [
+                `          if [ -z "$${name}" ]; then`,
+                `            echo "::warning::${name} is not set"`,
+                '            missing=1',
+                '          fi',
+            ]),
+            '          if [ "$missing" -eq 0 ]; then',
+            '            echo "ready=true" >> "$GITHUB_OUTPUT"',
+            '          else',
+            '            echo "ready=false" >> "$GITHUB_OUTPUT"',
+            '          fi',
+        ]
+        : [];
+    const suiteSteps = profile.suites.flatMap((suite) => [
+        `      - name: ${suite.id}`,
+        ...(guarded ? ["        if: steps.creds.outputs.ready == 'true'"] : []),
+        ...(guarded
+            ? [
+                '        env:',
+                ...profile.secrets.map((name) => `          ${name}: \${{ secrets.${name} }}`),
+            ]
+            : []),
+        `        run: ${suite.command}`,
+    ]);
+    const skippedSteps = guarded
+        ? [
+            '      - name: Report a skipped gate',
+            "        if: steps.creds.outputs.ready != 'true'",
+            '        run: |',
+            `          echo "::error::The eval gate could not run: set ${profile.secrets.join(', ')} as ${profile.secrets.length === 1 ? 'a repository secret' : 'repository secrets'}."`,
+            '          exit 1',
+        ]
+        : [];
+    const content = [
+        `# Generated once by \`aid gen\` for the \`${profile.target}\` target, then yours.`,
+        '# A scaffold file is never overwritten and never recorded in aid.manifest.json.',
+        '# Evals measure a real model, so this workflow needs the model credential; it runs',
+        '# on demand and nightly rather than on pull requests, which cannot hold a secret.',
+        'name: Evals',
+        '',
+        'on:',
+        '  workflow_dispatch:',
+        '  schedule:',
+        "    - cron: '0 6 * * *'",
+        '',
+        'concurrency:',
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: a GitHub Actions expression, emitted literally.
+        '  group: evals-${{ github.workflow }}-${{ github.ref }}',
+        '  cancel-in-progress: false',
+        '',
+        'permissions:',
+        '  contents: read',
+        '',
+        'jobs:',
+        '  evals:',
+        '    name: Eval gate',
+        '    runs-on: ubuntu-latest',
+        '    timeout-minutes: 30',
+        '    steps:',
+        `      - uses: ${ACTION_PINS.checkout}`,
+        ...lines(profile.toolchain, '      '),
+        '      - name: Install dependencies',
+        '        run: |',
+        ...lines(profile.install, '          '),
+        ...credentialSteps,
+        ...suiteSteps,
+        ...skippedSteps,
+        '',
+    ].join('\n');
+    return { path: EVALS_WORKFLOW_PATH, content, owner: 'scaffold' };
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/scaffold.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aid-framework/generator-sdk",
-  "version": "0.1.58",
+  "version": "0.1.59",
   "description": "The AID Framework generator plugin interface: the manifest contract, the drift/ownership algorithm, and the determinism helpers every target generator emits through.",
   "license": "Apache-2.0",
   "repository": {
@@ -30,8 +30,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@aid-framework/ir": "0.1.58",
-    "@aid-framework/spec": "0.1.58"
+    "@aid-framework/ir": "0.1.59",
+    "@aid-framework/spec": "0.1.59"
   },
   "devDependencies": {
     "@types/node": "^26.6.5"