@biffo/cli 0.303.3 → 0.304.0

package/_skeletons/plugin-template/README.md

@@ -137,7 +137,7 @@ repository with its own independent `uv sync` / `uv.lock`, not inside
 biffo-template's workspace. Once copied out, `uv sync && uv run pytest`
 works standalone with no dependency on the rest of biffo-template.
 
-## The `biffo-plugin-sdk` dependency: PyPI pin, pending the first release
+## The `biffo-plugin-sdk` dependency: PyPI pin
 
 `pyproject.toml` declares:
 
@@ -148,41 +148,30 @@ dependencies = [
 ]
 ```
 
-This is a **PyPI-style version pin**, and it is the correct end state: the
-SDK is versioned `1.0.0` and biffo-template's
+This is a **PyPI-style version pin**: the SDK is published via
+biffo-template's
 [`.github/workflows/publish-sdk.yml`](https://github.com/keiranholloway/biffo-template/blob/main/.github/workflows/publish-sdk.yml)
-builds and publishes it to PyPI (via Trusted Publishing) on a pushed
-`sdk-v*` tag. `>=1.0,<2.0` matches the `"biffo-plugin-sdk": "^1.0"` that
+(Trusted Publishing) on a pushed `sdk-v*` tag, and the first release has
+already happened — this skeleton's own `uv.lock` resolves `biffo-plugin-sdk`
+1.4.0 from `https://pypi.org/simple` (see its `biffo-plugin-sdk` entry).
+`>=1.0,<2.0` matches the `"biffo-plugin-sdk": "^1.0"` that
 `biffo.plugin.json` declares, and the SDK carries its own independent
 semver — it is **not** tied to the template's core version, so a major
 bump here means the plugin API broke and nothing else.
 
-**Ordering caveat.** The release _pipeline_ exists; the _release_ does not
-yet. `biffo-plugin-sdk` has never been uploaded — the PyPI project is
-unregistered until the owner configures the Trusted Publisher and pushes
-`sdk-v1.0.0`. Until that happens, `uv sync` in a freshly-copied plugin repo
-still cannot resolve this dependency, and you need one of the two local
-overrides below. Once 1.0.0 is live, **delete the override** — the
-`dependencies` entry above already points at the real thing.
-
-Two ways to make local development work before that happens:
-
-1. **Path dependency** (if developing inside a biffo-template checkout,
-   e.g. for a plugin you plan to upstream into `services/`): add
-   ```toml
-   [tool.uv.sources]
-   biffo-plugin-sdk = { path = "../../packages/python-sdk", editable = true }
-   ```
-2. **Git dependency** (developing this plugin as a genuinely separate repo
-   against an unpublished SDK):
-   ```toml
-   [tool.uv.sources]
-   biffo-plugin-sdk = { git = "https://github.com/keiranholloway/biffo-template", subdirectory = "packages/python-sdk" }
-   ```
-
-Either override goes in `[tool.uv.sources]` only — the PyPI-style
-`dependencies` entry above stays as-is, so removing the override is the
-only change needed once the SDK actually ships to PyPI.
+`uv sync` in a freshly-copied plugin repo resolves this pin normally; no
+`[tool.uv.sources]` override is needed. If you are developing this plugin
+*inside* a `biffo-template` checkout (e.g. one you plan to upstream into
+`services/`) and want to iterate against an unreleased SDK change before it
+ships, a local override still works:
+
+```toml
+[tool.uv.sources]
+biffo-plugin-sdk = { path = "../../packages/python-sdk", editable = true }
+```
+
+Keep it local (uncommitted, or removed before committing) — the PyPI-style
+`dependencies` entry above is what every scaffolded plugin repo ships with.
 
 ## Manifest validation: why CI doesn't hard-gate on `registry-schema.json`
 

package/_skeletons/plugin-template/pyproject.toml

@@ -4,22 +4,14 @@ version = "0.1.0"
 description = "Example Biffo plugin — replace this with your own plugin's name and description"
 requires-python = ">=3.13"
 dependencies = [
-  # biffo-plugin-sdk has a real release path as of biffo-template's
-  # .github/workflows/publish-sdk.yml: the package is versioned 1.0.0 and
-  # publishes to PyPI (via Trusted Publishing) when an `sdk-v*` tag is
-  # pushed. This pin is therefore the *correct end state* and is left as-is.
-  #
-  # ORDERING: the pin only resolves once the owner has actually pushed
-  # `sdk-v1.0.0` and PyPI has the release. Until that first publish,
-  # `uv sync` in a freshly-copied plugin repo cannot resolve it — the same
-  # as before this comment was written, so nothing regressed here; what
-  # changed is that the fix is now one tag push away rather than unbuilt.
-  # Deliberately NOT worked around with a git/path source in the committed
-  # file: baking one in would mean every plugin repo forked from this
-  # skeleton silently keeps building against a moving git ref long after
-  # the real release exists. Use a local `[tool.uv.sources]` override until
-  # then — see the README's "biffo-plugin-sdk dependency" section, which
-  # documents both options and says which to delete once 1.0.0 is live.
+  # biffo-plugin-sdk has a real release path via biffo-template's
+  # .github/workflows/publish-sdk.yml: it publishes to PyPI (via Trusted
+  # Publishing) when an `sdk-v*` tag is pushed. That first publish has
+  # already happened — this skeleton's own uv.lock resolves biffo-plugin-sdk
+  # 1.4.0 from https://pypi.org/simple (see uv.lock's own `biffo-plugin-sdk`
+  # entry) — so `uv sync` in a freshly-copied plugin repo resolves this pin
+  # normally, with no `[tool.uv.sources]` override needed (biffo-template#1769
+  # side finding).
   "biffo-plugin-sdk>=1.0,<2.0",
   "aws-lambda-powertools[tracer]>=3.4.0",
   "httpx>=0.28.1",

package/dist/index.js

@@ -4993,6 +4993,15 @@ var DnsSchema = z5.object({
   mode: z5.enum(["managed-route53", "external", "none"]).default("managed-route53"),
   domain: z5.string().min(1).optional()
 });
+var DesignTokensSchema = z5.object({
+  package: z5.string().min(1).describe(
+    `npm package providing this instance's real type scale, e.g. "@tabsii-com/ui". Added as an apps/frontend dependency of every new sibling, alongside (not instead of) @biffo/design-tokens -- biffo-scale-guard's own bin still ships from there.`
+  ),
+  version: z5.string().min(1).default("*").describe("Version range to pin `package` at in a new sibling's apps/frontend/package.json"),
+  path: z5.string().min(1).describe(
+    `Path to the CSS file declaring the --text-*/--space-* scale, relative to the package root (e.g. "dist/tokens.css"). Used for both the new sibling's globals.css @import and biffo-scale-guard's --tokens argument.`
+  )
+});
 var BiffoConfigSchema = z5.object({
   $schema: z5.string().optional(),
   project: z5.object({
@@ -5013,7 +5022,8 @@ var BiffoConfigSchema = z5.object({
     schema_path: z5.string().nullable().default(null),
     migrations_path: z5.string().default("services/api/migrations")
   }).default({}),
-  modules: ModulesSchema.default({})
+  modules: ModulesSchema.default({}),
+  design_tokens: DesignTokensSchema.optional()
 }).superRefine((config, ctx) => {
   const dns = resolveDnsConfig(config);
   if (dns.mode !== "none" && !dns.domain) {
@@ -6997,6 +7007,9 @@ async function runSiblingCreateCommand(name, options) {
 `
   );
 }
+async function defaultRelockFrontendDeps(cwd) {
+  await execa("pnpm", ["install", "--lockfile-only"], { cwd });
+}
 async function runSiblingCreate(github, aws, coreAws, git, config, session, options) {
   const totalSteps = 9;
   const { org, repo } = githubRepo(config);
@@ -7059,7 +7072,8 @@ async function runSiblingCreate(github, aws, coreAws, git, config, session, opti
         cloneUrl,
         config,
         options.coreConfig,
-        options.githubToken
+        options.githubToken,
+        options.relockFrontendDeps ?? defaultRelockFrontendDeps
       );
     }
     markSiblingStepComplete(session, "push_skeleton");
@@ -7219,7 +7233,7 @@ async function resolveCoreIdentity(coreAws, coreConfig, environments) {
   }
   return coreIdentity;
 }
-async function pushSkeleton(git, skeletonRoot, cloneUrl, config, coreConfig, githubToken) {
+async function pushSkeleton(git, skeletonRoot, cloneUrl, config, coreConfig, githubToken, relockFrontendDeps) {
   const workDir = mkdtempSync4(join24(tmpdir4(), `biffo-sibling-${config.project.name}-`));
   try {
     writeSiblingTemplate(skeletonRoot, workDir, config, {
@@ -7228,8 +7242,12 @@ async function pushSkeleton(git, skeletonRoot, cloneUrl, config, coreConfig, git
       // The core template's version at scaffold time (issue #567) — visibility
       // only, mirroring how `biffo init` stamps `biffo.core.json`. See the
       // `template_version` field doc on `SiblingMarker` (lib/sibling-teardown.ts).
-      templateVersion: getLatestCoreVersion()
+      templateVersion: getLatestCoreVersion(),
+      designTokens: coreConfig.design_tokens
     });
+    if (coreConfig.design_tokens) {
+      await relockFrontendDeps(join24(workDir, "apps", "frontend"));
+    }
     await git.init(workDir, "dev");
     await git.addRemote(workDir, "origin", cloneUrl);
     await git.add(workDir, ["."]);
@@ -7282,6 +7300,53 @@ function writeSiblingTemplate(templateRoot, targetDir, config, context) {
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
   }
+  if (context.designTokens) {
+    rewriteDesignTokens(targetDir, context.designTokens);
+  }
+}
+function rewriteDesignTokens(targetDir, tokens) {
+  const importSpecifier = `${tokens.package}/${tokens.path}`;
+  const packageJsonPath = join24(targetDir, "apps", "frontend", "package.json");
+  try {
+    const pkg = JSON.parse(readFileSync17(packageJsonPath, "utf8"));
+    pkg.dependencies = { ...pkg.dependencies, [tokens.package]: tokens.version };
+    writeFileSync7(packageJsonPath, JSON.stringify(pkg, null, 2) + "\n");
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+  const globalsCssPath = join24(targetDir, "apps", "frontend", "src", "app", "globals.css");
+  try {
+    const css = readFileSync17(globalsCssPath, "utf8").replace(
+      /^@import '@biffo\/design-tokens\/tokens\.css';$/m,
+      `@import '${importSpecifier}';`
+    );
+    writeFileSync7(globalsCssPath, css);
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+  const ciYmlPath = join24(targetDir, ".github", "workflows", "ci.yml");
+  try {
+    let yml = readFileSync17(ciYmlPath, "utf8");
+    yml = yml.replace(
+      /^(\s*run: pnpm exec biffo-scale-guard)$/m,
+      `$1 --tokens node_modules/${importSpecifier}`
+    );
+    yml = yml.replace(
+      "    timeout-minutes: 20\n    defaults:\n      run:\n        working-directory: apps/frontend\n    steps:",
+      "    timeout-minutes: 20\n    permissions:\n      contents: read\n      packages: read\n    defaults:\n      run:\n        working-directory: apps/frontend\n    steps:"
+    );
+    yml = yml.replace(
+      "    continue-on-error: true\n    defaults:\n      run:\n        working-directory: apps/frontend\n    steps:",
+      "    continue-on-error: true\n    permissions:\n      contents: read\n      packages: read\n    defaults:\n      run:\n        working-directory: apps/frontend\n    steps:"
+    );
+    yml = yml.replace(
+      /( {6}- run: pnpm install --frozen-lockfile)\n(?! {8}env:)/g,
+      "$1\n        env:\n          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n"
+    );
+    writeFileSync7(ciYmlPath, yml);
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
 }
 async function configureSiblingGithub(github, config, coreConfig, session, coreIdentity) {
   const { org, repo } = githubRepo(config);
@@ -8273,7 +8338,8 @@ import {
 import { dirname as dirname7, join as join26 } from "path";
 var STANDALONE_ONLY_ENTRIES = {
   ".github": "standalone-repo CI/release workflows \u2014 the host monorepo already runs lint/type/test/security over services/",
-  "registry-schema.json": "the plugin-registry publishing schema, used when submitting a *published* plugin to the registry repo, not by an in-tree plugin"
+  "registry-schema.json": "the plugin-registry publishing schema, used when submitting a *published* plugin to the registry repo, not by an in-tree plugin",
+  "uv.lock": "a standalone repo's own lockfile, substituted like any other text file (issue #1769) \u2014 a nested lock inside a monorepo's services/ would be wrong there, since the host resolves its own dependency tree"
 };
 var NEVER_COPY = /* @__PURE__ */ new Set([
   ".git",
@@ -8284,7 +8350,6 @@ var NEVER_COPY = /* @__PURE__ */ new Set([
   ".pytest_cache",
   ".mypy_cache",
   "dist",
-  "uv.lock",
   ".DS_Store"
 ]);
 var PLUGIN_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
@@ -8537,6 +8602,11 @@ async function runStandaloneCreate(names, options, deps) {
 `
   );
   if (options.commit) {
+    if (!existsSync27(join27(destDir, "uv.lock"))) {
+      throw new Error(
+        `Scaffolded plugin at ${destDir} has no uv.lock. The standalone layout must carry a substituted uv.lock (see plugin-scaffold.ts STANDALONE_ONLY_ENTRIES) so the first commit's CI run can satisfy 'uv sync --locked'. Refusing to commit a repo that would ship red on its very first push (issue #1769) \u2014 run 'uv lock' in ${destDir} first.`
+      );
+    }
     await deps.git.init(destDir);
     await deps.git.add(destDir, ["."]);
     await deps.git.commit(destDir, `feat: scaffold ${names.slug} plugin`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.303.3",
+  "version": "0.304.0",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",