@stndrds/cli 1.0.0-alpha.258 → 1.0.0-alpha.260

package/dist/assets/standards-drift.yml

@@ -0,0 +1,242 @@
+name: Standards schema/view drift
+
+# Runs "standards diff" against the deployed (prod) Standards instance on every
+# PR, so schema/view drift that would be silently overwritten or destroyed on
+# the next deploy is caught at review time instead of after rollout.
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  standards-drift:
+    name: standards diff
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Enable corepack (pnpm)
+        run: corepack enable
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # `standards diff` reads its credentials the same way every other CLI
+      # command does (see packages/cli/src/config.ts:resolveCliConfig /
+      # getEnvProfile): STANDARDS_API_URL + STANDARDS_API_KEY. These are the
+      # exact env var names the client reads — do not rename without updating
+      # both the CLI and this workflow.
+      #
+      # `--format json` is captured for the PR comment step below; the human-
+      # readable table is still what a developer sees if they run the same
+      # command locally without --format. Stderr is captured separately
+      # (`standards diff` prints its exit-2 failure message via
+      # `console.error`, i.e. to stderr, never into the JSON stdout) so the
+      # comment step has something to show for an infra failure instead of an
+      # empty code block.
+      - name: Run standards diff
+        id: standards-diff
+        env:
+          STANDARDS_API_URL: ${{ secrets.STANDARDS_API_URL }}
+          STANDARDS_API_KEY: ${{ secrets.STANDARDS_API_KEY }}
+        run: |
+          set +e
+          pnpm exec standards diff --format json > standards-diff.json 2> standards-diff.err
+          echo "exit_code=$?" >> "$GITHUB_OUTPUT"
+          cat standards-diff.json
+          cat standards-diff.err >&2
+          exit 0
+
+      # Fork PRs run with a read-only GITHUB_TOKEN (no `pull-requests: write`),
+      # so `github.rest.issues.createComment`/`updateComment` below would 403.
+      # Skip the comment (not the check itself — "Fail the job" below still
+      # runs and still gates the merge) for PRs from forks. See the maintainer
+      # note at the bottom of this file.
+      - name: Comment drift report on PR
+        if: github.event.pull_request.head.repo.full_name == github.repository
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require("fs");
+            const exitCode = Number("${{ steps.standards-diff.outputs.exit_code }}");
+            const marker = "<!-- standards-drift-report -->";
+
+            const stdout = fs.existsSync("standards-diff.json") ? fs.readFileSync("standards-diff.json", "utf-8") : "";
+            const stderr = fs.existsSync("standards-diff.err") ? fs.readFileSync("standards-diff.err", "utf-8") : "";
+
+            let report = null;
+            if (stdout.trim().length > 0) {
+              try {
+                report = JSON.parse(stdout);
+              } catch {
+                // exit code 2 (infra failure) can leave non-JSON stdout (e.g.
+                // the process never got far enough to print a report) — the
+                // stderr capture above is what carries the actual message then.
+              }
+            }
+
+            // `state !== "in-sync"` on its own would lump `code-changed`/
+            // `conflict-resolved` (informational — will simply apply, nothing
+            // blocking) in with `conflict`/`runtime-diverged` (blocking,
+            // needs a developer decision). Keep them in separate tables so
+            // the "needs a decision" table is true of every row it lists.
+            function renderTable(rows) {
+              if (rows.length === 0) return "_None._";
+              const header = "| View | State | Changed fields |\n| --- | --- | --- |";
+              const body = rows
+                .map((v) => `| \`${v.key}\` | ${v.state} | ${(v.changedFields ?? []).join(", ") || "—"} |`)
+                .join("\n");
+              return `${header}\n${body}`;
+            }
+
+            function renderDecisionViewsTable(views) {
+              return renderTable(views.filter((v) => v.state === "conflict" || v.state === "runtime-diverged"));
+            }
+
+            function renderInformationalViewsTable(views) {
+              return renderTable(views.filter((v) => v.state === "code-changed" || v.state === "conflict-resolved"));
+            }
+
+            function renderSchemaTable(schema) {
+              const lines = [];
+              for (const obj of schema?.customObjects ?? []) {
+                lines.push(`| \`${obj.name}\` | custom object, not in code |`);
+              }
+              for (const entry of schema?.systemObjectDrift ?? []) {
+                const unexpected = entry.sealed
+                  ? entry.customAttributes.filter((a) => !a.tolerated)
+                  : [];
+                if (entry.sealed && unexpected.length > 0) {
+                  lines.push(
+                    `| \`${entry.objectName}\` | ${unexpected.length} unexpected attribute(s) (sealed) |`
+                  );
+                }
+              }
+              if (lines.length === 0) return "_No object/attribute drift._";
+              return `| Object | Note |\n| --- | --- |\n${lines.join("\n")}`;
+            }
+
+            let body;
+            if (exitCode === 2) {
+              const details = stderr.trim().length > 0 ? stderr.trim() : stdout.trim().length > 0 ? stdout.trim() : "(no output captured)";
+              body = [
+                marker,
+                "## ⚠️ standards diff — could not run (exit code 2)",
+                "",
+                "This is an **infra/configuration failure**, not schema or view drift —",
+                "the check itself did not complete. Common causes: a missing or invalid",
+                "`STANDARDS_API_URL` / `STANDARDS_API_KEY` secret, an unreachable API, or a",
+                "schema entry file that fails to load in isolation.",
+                "",
+                "```",
+                details,
+                "```",
+              ].join("\n");
+            } else if (exitCode === 0) {
+              body = [marker, "## ✅ standards diff — no blocking drift", "", "Next deploy is a no-op for schema/views."].join(
+                "\n"
+              );
+            } else {
+              body = [
+                marker,
+                "## 🚫 standards diff — unresolved drift (exit code 1)",
+                "",
+                "### Needs a decision",
+                "",
+                "These views WOULD have their runtime change overwritten or destroyed by",
+                "the next deploy. Run `standards pull` locally to resolve each one (promote",
+                "the runtime change into code, or explicitly overwrite it), then push again.",
+                "",
+                renderDecisionViewsTable(report?.views ?? []),
+                "",
+                "### Will apply automatically (informational, no action needed)",
+                "",
+                renderInformationalViewsTable(report?.views ?? []),
+                "",
+                "### Schema (objects/attributes)",
+                "",
+                renderSchemaTable(report?.schema ?? {}),
+              ].join("\n");
+            }
+
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            const existing = comments.find((c) => c.body?.includes(marker));
+
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }
+
+      - name: Fail the job on unresolved drift or infra failure
+        if: steps.standards-diff.outputs.exit_code != '0'
+        run: |
+          echo "standards diff exited with code ${{ steps.standards-diff.outputs.exit_code }}"
+          exit 1
+
+# ---------------------------------------------------------------------------
+# Notes for whoever maintains this workflow
+# ---------------------------------------------------------------------------
+#
+# 1. Deploy-time re-check (close the merge -> deploy TOCTOU window):
+#    A PR can be green here and still go stale — a runtime user can edit a
+#    view in the time between "this PR merged" and "this commit actually
+#    deployed". Copy the "Run standards diff" step (same env vars, same
+#    command) into your deploy pipeline immediately BEFORE the rollout step,
+#    and treat a non-zero exit there as a deploy abort:
+#      - exit 1 -> abort the deploy, drift must be resolved first (the exact
+#        same resolution flow as above: `standards pull`, or hand this off to
+#        the `standards-pull` agent skill).
+#      - exit 2 -> abort the deploy, this is an infra failure (bad
+#        credentials, unreachable API), not a drift decision.
+#    Without this second check, this PR-time gate only protects the instant
+#    of merge, not the instant of deploy.
+#
+# 2. v1 assumes single-tenant consumer deployments: one STANDARDS_API_KEY
+#    maps to exactly one tenant. If your deployment serves multiple tenants
+#    per Standards instance, this workflow (and `standards diff`/`standards
+#    pull` generally) only checks the one tenant reachable with the configured
+#    key — repeat the job (or the deploy-time re-check) once per tenant.
+#
+# 3. Exit codes, spelled out (see packages/cli/src/commands/diff.ts):
+#      0 = no blocking drift, next deploy is a no-op for schema/views.
+#      1 = blocking drift found (an unresolved conflict, or unexpected sealed-
+#          object drift) — the next deploy WOULD destroy runtime changes.
+#      2 = infra failure: network/auth error, missing/invalid
+#          STANDARDS_API_URL / STANDARDS_API_KEY, or the schema entry failed
+#          to load in isolation. This is NOT drift — do not treat it as "no
+#          drift" (it is not 0) and do not treat it as a conflict to resolve
+#          (editing schema code will not fix a missing secret).
+#
+# 4. Fork PRs: GitHub gives a `pull_request` run triggered from a fork a
+#    read-only GITHUB_TOKEN (no `pull-requests: write`), so the "Comment
+#    drift report on PR" step is guarded with
+#    `if: github.event.pull_request.head.repo.full_name == github.repository`
+#    and is simply skipped for fork PRs — it would otherwise fail with a 403
+#    trying to post the comment. The "Fail the job on unresolved drift or
+#    infra failure" step is NOT guarded — it doesn't call the GitHub API, so
+#    it still gates the merge for fork PRs; the developer just won't get the
+#    rendered table, only the job's own log output (which still contains the
+#    exit code and, on exit 2, the captured stderr).

package/dist/assets/standards-pull-skill.md

@@ -0,0 +1,101 @@
+---
+name: standards-pull
+description: Resolve Standards schema/view drift between the code-defined schema and the deployed runtime — walks each conflicting or runtime-diverged view with the developer, promotes runtime changes into builder code, and only stops once "standards diff" reports no drift. Use when "standards diff" exits 1, when a PR's standards-drift CI check fails, or when the developer asks to resolve/promote/reconcile schema or view drift.
+---
+
+# standards-pull — resolve schema/view drift
+
+## What drift means here
+
+Standards is schema-driven: the code-defined schema (`object()`/`view()` builders) is
+the source of truth, and it gets synced into the runtime database on deploy. Between
+deploys, runtime users can edit views (labels, tabs, field layout) through the product
+UI. `standards diff` compares the two and classifies every view into one of:
+
+- `code-changed` — only code changed since the last sync; the next deploy will simply
+  apply it. Nothing to do.
+- `runtime-diverged` — a runtime user changed the view and code has NOT changed it;
+  the next deploy would silently overwrite their change. Needs a decision.
+- `conflict` — BOTH code and the runtime changed the same view since the last sync.
+  The next deploy WOULD DESTROY the runtime change. Blocking (exit code 1).
+- `conflict-resolved` — a conflict that a developer already acknowledged via
+  `standards pull`'s "overwrite" decision; code will apply cleanly.
+- `in-sync` — no drift, no line printed.
+
+Exit codes (`standards diff` / `standards pull`): `0` = nothing blocking, `1` = at
+least one `conflict` or sealed-object drift is unresolved, `2` = infra failure
+(network error, the schema entry failed to load, misconfigured/missing credentials).
+**Exit code 2 is not drift** — it means the check itself could not run (e.g. a CI job
+with a missing `STANDARDS_API_KEY` secret). Never treat a `2` as "no drift" or as a
+conflict to resolve; fix the underlying infra/config problem and re-run.
+
+## Your job, precisely
+
+You are invoked either because a developer asked you to resolve drift, or because a
+CI check (`standards-drift.yml`) is failing on a PR. In both cases:
+
+1. Run `standards diff --format json` and parse the JSON report. This is the ONLY
+   source of truth for what has drifted — never guess from reading builder files
+   alone, and never rely on a stale report from earlier in the conversation.
+2. If the exit code is `2`, STOP and report the infra error message to the developer
+   verbatim — this is not something you can resolve by editing schema code (missing
+   `STANDARDS_API_KEY`/`STANDARDS_API_URL`, unreachable API, a schema entry that fails
+   to load in isolation). Fix what's actually broken (e.g. a bad import in the entry
+   file) and re-run `standards diff` before doing anything else.
+3. If the exit code is `0`, there is nothing to do — say so and stop.
+4. Otherwise, walk every item in the report **with the developer** — do not
+   silently decide on their behalf for anything destructive:
+   - `conflict` and `runtime-diverged` views are what need a decision. For each one,
+     tell the developer what changed on each side (the report's `changedFields`) and
+     ask: **promote** the runtime change into code, or (for `conflict` only)
+     **overwrite** it by running `standards pull` and choosing "Overwrite" for that
+     view (accepts the code version, discards the runtime change — only do this with
+     explicit developer confirmation, it is destructive to the runtime edit).
+   - `customObjects` / unexpected `systemObjectDrift` attributes: tell the developer
+     these exist only in the runtime, not in code, and ask whether to promote them
+     into the builder (add the attribute/object in code) or leave them as runtime-only
+     extensions.
+5. To **promote**: run `standards pull` and choose "Promote" for the relevant view.
+   This writes `.standards/promotions/<object>-<name>-<type>.md`, containing:
+   - the view's current **runtime config** (the JSON to fold into the builder call —
+     tabs, fields, label, icon, etc.)
+   - a **builder file hint**: the file path and line of the existing
+     `listView(...)`/`detailView(...)` call for that view, when one is found
+   Read that file, then edit the builder call in the hinted file so the fluent
+   builder chain (`.tab(...)`, `.form(...)`, `.label(...)`, etc.) produces the same
+   shape as the runtime config in the promotion file. This is a translation task —
+   the promotion file gives you the target *data*, you write the target *code*.
+6. **Loop `standards diff` until it exits 0.** After every edit (a promotion applied,
+   an overwrite decided, a builder file changed), re-run `standards diff --format
+   json` and re-parse it. Do not stop after one pass over the report — new drift can
+   surface (e.g. an edit that doesn't fully match the promoted config still shows as
+   `runtime-diverged`), and the loop is the only thing that proves you actually closed
+   every gap. **Never declare success without a green (`exitCode: 0`) `standards
+   diff` run.** A clean-looking diff of your own code edits is not sufficient — the
+   deterministic tool is what closes the loop, not your judgment about whether the
+   edits "look right".
+
+## Guardrails
+
+- Never run `standards pull`'s "Overwrite" decision without explicit developer
+  confirmation for that specific view — it discards real runtime user edits.
+- Never hand-edit `.standards/config.json` or `.standards/promotions/*.md` — those
+  are written by the CLI (`standards init` / `standards pull`); editing them by hand
+  does not change what the runtime actually has and will desync your mental model
+  from `standards diff`'s next run.
+- If a promotion file's builder hint says "No `listView`/`detailView` call found",
+  search the schema entry's directory yourself for where that object's other views
+  are declared — the view may be newly created at runtime and have no code
+  counterpart yet; promoting it means adding a NEW builder call, not editing one.
+- If `standards diff` keeps reporting the same drift after an edit you believe is
+  correct, re-read the promotion file's runtime config carefully — a mismatched field
+  name, tab id, or attribute list is the most common cause, not a tooling bug.
+
+## Related: deploy-time re-check
+
+The merge of a PR and the actual deploy of that code are two different moments in
+time — a runtime user can edit a view in the window between them. Projects that wired
+`standards init --ci` should also run `standards diff` as a gate immediately before
+the deploy step in their deploy pipeline (exit code `1` aborts the rollout), so this
+skill's job — reconciling runtime drift — never gets skipped by that gap. If asked to
+set that up, see the comment block at the end of `.github/workflows/standards-drift.yml`.