@sequenceholdings/artifact-studio 0.3.1 → 0.5.0

package/README.md

@@ -3,11 +3,82 @@
 `@sequenceholdings/artifact-studio` exposes the host-provided `seq` client. Runtime
 requests use the current user's normal permissions.
 
+## Governed ORM operations
+
+Use the published caller-aware adapter inside an Artifact Studio Preview or a
+deployed artifact. Generate and apply the namespace first, then import its
+`operations.manifest.json` into your application:
+
+```ts
+import { createArtifactOrmExecutor } from '@sequenceholdings/artifact-studio'
+import manifest from './operations.manifest.json'
+
+const orm = createArtifactOrmExecutor({ namespace: 'team_directory', manifest })
+const result = await orm.execute('Profiles', { limit: 100, offset: 0 })
+```
+
+Declare the exact namespace path in `artifact.bundle.yml`:
+
+```yaml
+capabilities:
+  api:
+    write: ['/api/data/v2/team_directory']
+```
+
+Persisted queries and mutations both use POST, so both require this `write`
+declaration. This declaration permits the artifact to make the request; each
+user still needs namespace runtime access and the operation's role/capability.
+ORM row policies and write checks enforce that caller's access. The helper uses
+host authentication and requires no token, custom header, or environment URL.
+The namespace path above is a capability declaration, not a direct HTTP API
+contract for external clients.
+
+The adapter validates the namespace and manifest, rejects unknown operations,
+and returns the operation's `data`. Errors retain `OrmOperationError.status`,
+`code`, and `errors`; missing host context or malformed success responses fail
+instead of reporting saved data. The adapter never retries a call automatically. For
+several operations in one traced UI action, pass `withTraceAction`'s client as
+the optional `sdk` argument.
+
+### Exact numbers
+
+By default `numeric` and `bigint` values come back as JSON numbers, which
+JavaScript rounds past 15-17 significant digits; a form that saves what it read
+would write the rounded value back. Ask for strings instead:
+
+```ts
+const orm = createArtifactOrmExecutor({ namespace: 'lending', manifest, jsonScalars: 'lossless-v1' })
+// A Next.js server component, route handler or Server Action:
+const db = client.orm({ namespace: 'lending', manifest, jsonScalars: 'lossless-v1' })
+```
+
+Results then carry these columns as strings (`"250000.00"`,
+`"9007199254740993"`). The executor refuses any successful result the platform
+does not acknowledge in that form, with `OrmOperationError` code
+`LOSSLESS_TRANSPORT_UNAVAILABLE`, so an older Atlas can never hand back rounded
+money as exact. Send `numeric` and `bigint` variables as decimal strings in
+either mode, and avoid `Number`/`parseFloat` on exact values.
+
 Artifact Studio is a workflow-agnostic platform primitive. The host, SDK, and
 deployer provide generic application capabilities; each deployed artifact owns
 its product behavior. Primitive code must not branch on an artifact ID or import
 an application's services. See [Platform primitive boundaries](../../../docs/platform/platform-primitives.md).
 
+## Lost connections in a Next.js server
+
+The server client (`@sequenceholdings/artifact-studio/server`) sends a read up
+to three times when its connection to Atlas fails before Atlas answers: the
+connection was refused or reset, the host or network was unreachable, or a DNS
+lookup failed transiently. It pauses up to 100 ms, then up to 200 ms, and logs a
+`broker.reconnect` warning for each resend. Reads are `client.orm` operations
+the manifest lists with `kind: 'query'`, `client.api` GET and HEAD requests,
+Storage GET and HEAD requests, and flag evaluations. ORM mutations, other API
+methods, Storage writes, function invokes and process starts are sent once,
+because a reset can come after Atlas acted on them, and reject with fetch's
+`TypeError: fetch failed` as before. (Audit delivery keeps its own single
+resend under the same event id.) A response with any status is Atlas's answer
+and is never resent.
+
 ## Grouping calls into a trace
 
 The Artifact host supplies tracing context automatically for supported platform

package/VERSION-PIN.md

@@ -21,6 +21,15 @@ Artifact Studio 0.3.1 (Studio CLI 0.2.2) verifies the per-request `jti` that the
 gateway now signs into every request context. The 0.3.0 context schema predates
 that claim and rejects those contexts, so Next.js applications need 0.3.1 or newer.
 
+The Artifact mobile-pattern source adds new atlas-ui exports. Roll that surface
+out in dependency order: publish atlas-ui from its changeset, update the exact
+`@sequenceholdings/atlas-ui` dependency in `artifact-studio/package.json`,
+publish Artifact Studio and Studio CLI, then migrate and redeploy artifact
+consumers. A source-linked candidate preview may exercise the new exports
+before publication; an ordinary released CLI intentionally cannot.
+The React/Vite starter therefore uses released primitives and responsive CSS
+until that pin advances. Its build test exercises the ordinary CLI toolchain.
+
 ## What this means
 
 `shared/services/artifact-studio/src/build.ts` force-aliases platform peers via

package/dist/active-deploy-policy.d.ts

@@ -1,7 +1,8 @@
 /**
- * Official (active-channel) Artifact Studio deploys must come from `main` with
- * a resolved commit and a clean artifact source directory — whether the source
- * is a platform git-service repo (`--repo`) or a monorepo / local checkout.
+ * Official (active-channel) Artifact Studio deploys must come from `main`, or
+ * from `staging` when the target is a staging environment, with a resolved
+ * commit and a clean artifact source directory — whether the source is a
+ * platform git-service repo (`--repo`) or a monorepo / local checkout.
  * Preview deploys may use feature branches, dirty trees, or other refs.
  *
  * This checks reported provenance (branch name + explicit clean flag + commit).
@@ -19,9 +20,12 @@ export interface ActiveDeployProvenance {
     gitCommit?: string | null;
     gitBranch?: string | null;
     gitDirty?: boolean | null;
+    environment?: string | null;
 }
 /** Canonical default branch name for official artifact deploys. */
 export declare const ACTIVE_DEPLOY_DEFAULT_BRANCH = "main";
+/** Branch allowed for official artifact deploys to staging environments. */
+export declare const ACTIVE_DEPLOY_STAGING_BRANCH = "staging";
 export declare class ActiveDeployPolicyError extends Error {
     readonly code: "ACTIVE_DEPLOY_POLICY";
     constructor(message: string);
@@ -29,6 +33,8 @@ export declare class ActiveDeployPolicyError extends Error {
 /** Strip `refs/heads/` so `refs/heads/main` and `main` compare equal. */
 export declare function normalizeGitBranchName(branch: string | null | undefined): string | null;
 export declare function isActiveDeployDefaultBranch(branch: string | null | undefined): boolean;
+/** Recognize first-party and provisioned staging environment names. */
+export declare function isStagingEnvironment(environment: string | null | undefined): boolean;
 /**
  * Throw if provenance is not eligible for an official (active) deploy.
  * Preview callers must not invoke this.

package/dist/active-deploy-policy.js

@@ -1,7 +1,8 @@
 /**
- * Official (active-channel) Artifact Studio deploys must come from `main` with
- * a resolved commit and a clean artifact source directory — whether the source
- * is a platform git-service repo (`--repo`) or a monorepo / local checkout.
+ * Official (active-channel) Artifact Studio deploys must come from `main`, or
+ * from `staging` when the target is a staging environment, with a resolved
+ * commit and a clean artifact source directory — whether the source is a
+ * platform git-service repo (`--repo`) or a monorepo / local checkout.
  * Preview deploys may use feature branches, dirty trees, or other refs.
  *
  * This checks reported provenance (branch name + explicit clean flag + commit).
@@ -17,6 +18,8 @@
  */
 /** Canonical default branch name for official artifact deploys. */
 export const ACTIVE_DEPLOY_DEFAULT_BRANCH = 'main';
+/** Branch allowed for official artifact deploys to staging environments. */
+export const ACTIVE_DEPLOY_STAGING_BRANCH = 'staging';
 export class ActiveDeployPolicyError extends Error {
     code = 'ACTIVE_DEPLOY_POLICY';
     constructor(message) {
@@ -36,6 +39,11 @@ export function normalizeGitBranchName(branch) {
 export function isActiveDeployDefaultBranch(branch) {
     return normalizeGitBranchName(branch) === ACTIVE_DEPLOY_DEFAULT_BRANCH;
 }
+/** Recognize first-party and provisioned staging environment names. */
+export function isStagingEnvironment(environment) {
+    const normalized = environment?.trim().toLowerCase();
+    return normalized === 'staging' || normalized?.endsWith('_staging') === true || normalized?.endsWith('-staging') === true;
+}
 /**
  * Throw if provenance is not eligible for an official (active) deploy.
  * Preview callers must not invoke this.
@@ -52,18 +60,22 @@ export function assertActiveDeployProvenance(provenance) {
     }
     const branch = normalizeGitBranchName(provenance.gitBranch);
     if (!branch) {
-        throw new ActiveDeployPolicyError('Active (official) artifact deploys require git provenance on `main`. ' +
-            'Check out `main` (monorepo or local clone) or deploy with ' +
+        throw new ActiveDeployPolicyError('Active (official) artifact deploys require git provenance on `main` ' +
+            'or `staging` for a staging target. ' +
+            'Check out `main` (or `staging` for staging) in a monorepo or local clone, or deploy with ' +
             '`seq-studio artifact deploy --repo <ns>/<slug>` (defaults to the repo default branch). ' +
             'Feature branches and detached HEAD (unless at the tip of `main`) are preview-only.');
     }
-    if (branch !== ACTIVE_DEPLOY_DEFAULT_BRANCH) {
+    const stagingBranchAllowed = branch === ACTIVE_DEPLOY_STAGING_BRANCH && isStagingEnvironment(provenance.environment);
+    if (branch !== ACTIVE_DEPLOY_DEFAULT_BRANCH && !stagingBranchAllowed) {
         throw new ActiveDeployPolicyError(`Active (official) artifact deploys must use \`${ACTIVE_DEPLOY_DEFAULT_BRANCH}\` ` +
+            `or \`${ACTIVE_DEPLOY_STAGING_BRANCH}\` for staging targets ` +
             `(got branch/ref \`${branch}\`). Merge via a Pull, then redeploy from \`main\`; ` +
             'use a preview channel for feature-branch or dirty local work.');
     }
     if (!provenance.gitCommit?.trim()) {
-        throw new ActiveDeployPolicyError('Active (official) artifact deploys require a resolved git commit on `main`. ' +
-            'Deploy from a git checkout or `--repo` so provenance is recorded.');
+        throw new ActiveDeployPolicyError('Active (official) artifact deploys require a resolved git commit on `main` ' +
+            'or `staging` for a staging target. Deploy from a git checkout or `--repo` ' +
+            'so provenance is recorded.');
     }
 }

package/dist/artifact-env-bindings.d.ts

@@ -0,0 +1,9 @@
+/** Fail an artifact deploy whose source still points at another environment. */
+export declare function assertArtifactEnvironmentBindings({ directory, environment, token, }: {
+    directory: string;
+    environment: {
+        name: string;
+        url: string;
+    };
+    token: string;
+}): Promise<void>;

package/dist/artifact-env-bindings.js

@@ -0,0 +1,32 @@
+import { getJsonOr404 } from './api.js';
+import { knownEnvUrls } from './config.js';
+import { assertNoCrossEnvironmentBindings, canonicalDeploymentOrigin } from './env-bindings.js';
+import { readArtifactStudioSource } from './project.js';
+/** Fail an artifact deploy whose source still points at another environment. */
+export async function assertArtifactEnvironmentBindings({ directory, environment, token, }) {
+    const source = await readArtifactStudioSource(directory);
+    const deployOrigin = canonicalDeploymentOrigin(environment.url);
+    if (!deployOrigin)
+        throw new Error(`Invalid deployment URL '${environment.url}'.`);
+    const origins = Object.entries(knownEnvUrls()).flatMap(([name, url]) => {
+        const origin = canonicalDeploymentOrigin(url);
+        return origin ? [{ name, origin }] : [];
+    });
+    await assertNoCrossEnvironmentBindings({
+        deployEnvironment: environment.name,
+        deployOrigin,
+        origins,
+        workspaces: [],
+        files: source.files,
+        workspaceExists: async (workspaceId) => {
+            const workspace = await getJsonOr404({
+                baseUrl: environment.url,
+                token,
+                path: `/api/storage/workspaces/${workspaceId}`,
+            });
+            // The selected API already scopes this read to its storage environment,
+            // including local `local:<project>:<branch>` values.
+            return workspace !== null;
+        },
+    });
+}

package/dist/build.js

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { dirname, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { build as viteBuild } from 'vite';
 import { atlasUiCssResolverPlugin, collectAtlasUiResolvedTokenSelections, hasUnifiedAtlasUiTokens } from './atlas-ui-css-plugin.js';
 import { validateAtlasUiTokenStylesheetContract } from './atlas-ui-package-contract.js';
@@ -51,6 +52,10 @@ const atlasUiTokens = resolveAtlasUiTokensPath(atlasUiDir);
 // `seq-studio dev --link`) work.
 const formRendererDir = dirname(cliRequire.resolve('@sequenceholdings/lattice-form-renderer/package.json'));
 const formRendererDist = resolve(formRendererDir, 'dist');
+const artifactStudioModuleDir = dirname(fileURLToPath(import.meta.url));
+const offlineRuntimeEntry = existsSync(resolve(artifactStudioModuleDir, 'offline/index.js'))
+    ? resolve(artifactStudioModuleDir, 'offline/index.js')
+    : resolve(artifactStudioModuleDir, 'offline/index.ts');
 /**
  * Import aliases for the Vite build. Artifacts are built against their own
  * source tree, which usually has no installed node_modules, so every bare
@@ -78,6 +83,8 @@ function createPeerResolveAlias({ atlasUiPackageDir = atlasUiDir } = {}) {
         'react-router-dom': reactRouterDomDir,
         sonner: sonnerDir,
         '@sequenceholdings/storage': cliRequire.resolve('@sequenceholdings/storage'),
+        '@sequenceholdings/orm/client': cliRequire.resolve('@sequenceholdings/orm/client'),
+        '@sequenceholdings/artifact-studio/offline': offlineRuntimeEntry,
         // Candidate Atlas UI exposes canonical tokens at the package root; released
         // 2.0.1 keeps them in dist. Preserve explicit alias resolution so legacy
         // source reaches the normalizer instead of falling through to the bare alias.

package/dist/cli.js

@@ -16,8 +16,10 @@ import { runWatchLoop } from './watch-loop.js';
 import { hashLinkedSources, hasLinkedAtlasUiToolchain, parseLinks, rebuildLinkedDep, resolveLinkedDeps, syncLinkedDist, } from './dev-link.js';
 import { lintArtifactSandbox, reportSandboxWarnings } from './sandbox-lint.js';
 import { assertActiveDeployProvenance } from './active-deploy-policy.js';
+import { assertArtifactEnvironmentBindings } from './artifact-env-bindings.js';
 import { normalizeArtifactPath } from './paths.js';
 import yaml from 'js-yaml';
+import { warnOnRoleDefinitions } from './role-definitions-notice.js';
 const COMMANDS = [
     'init', 'whoami', 'link', 'env', 'status', 'list', 'show',
     'validate', 'build', 'plan', 'deploy', 'dev', 'promote', 'pull', 'rollback',
@@ -28,23 +30,26 @@ const USAGE = `usage:
   seq-studio artifact link --env <env> [--project <id>]
   seq-studio artifact env list|use <env>
   seq-studio artifact status [--env <env>]
-  seq-studio artifact list --env <env>
-  seq-studio artifact show <slug-or-id> --env <env>
+  seq-studio artifact list --env <env> [--json]
+  seq-studio artifact show <slug-or-id> --env <env> [--json]
   seq-studio artifact validate [dir]
-  seq-studio artifact build [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] [--out dist/artifact-bundle.json]
-  seq-studio artifact plan [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] --env <env>
-  seq-studio artifact deploy [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] --env <env> [--skip-unchanged] [--no-create] [--project <id>]
+  seq-studio artifact build [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] [--path <dir>] [--out dist/artifact-bundle.json]
+  seq-studio artifact plan [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] [--path <dir>] --env <env>
+  seq-studio artifact deploy [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] [--path <dir>] --env <env> [--skip-unchanged] [--no-create] [--project <id>]
   seq-studio artifact dev [dir] --env <env> [--once] [--key default] [--link <pkgDir>[,<pkgDir>]] [--port <port>]
   seq-studio artifact promote <deployment-id> --env <env>
   seq-studio artifact pull <project-id> --env <env> --out <dir>
   seq-studio artifact rollback <deployment-id> --env <env>
 
   Add --help or -h to any artifact command to print this usage without running it.
+  init includes AGENTS.md pointing to your environment's live docs, with a
+  CLAUDE.md import, for both templates.
 
   Source: a local [dir] (default), a platform git-service repo (--repo <ns>/<name>),
   or a public HTTPS git URL (--git-url <url>). --ref picks a branch/tag/commit (default: the
-  repo's default branch). The target project comes from the source's
-  artifact.bundle.yml project_id.
+  repo's default branch). --path <dir> selects the application directory inside a
+  --repo / --git-url repository (default: its root). The target project comes from
+  the source's artifact.bundle.yml project_id.
 
   Official (active) deploys to deployed environments require \`main\` with a
   resolved git commit and a clean artifact source directory. Dirty files
@@ -82,6 +87,11 @@ export async function runCli(argv = process.argv.slice(2)) {
         console.error(parsed.error);
         return 1;
     }
+    const optionError = validateKnownOptions(parsed);
+    if (optionError) {
+        console.error(optionError);
+        return 1;
+    }
     switch (parsed.command) {
         case 'init': return initCommand(parsed);
         case 'whoami': return whoamiCommand(parsed);
@@ -100,6 +110,34 @@ export async function runCli(argv = process.argv.slice(2)) {
         case 'rollback': return rollbackCommand(parsed);
     }
 }
+function validateKnownOptions(args) {
+    const options = {
+        init: { values: ['template'], booleans: [] }, whoami: { values: ['env'], booleans: [] },
+        link: { values: ['env', 'project'], booleans: [] }, env: { values: [], booleans: [] },
+        status: { values: ['env'], booleans: [] }, list: { values: ['env'], booleans: ['json'] },
+        show: { values: ['env'], booleans: ['json'] }, validate: { values: [], booleans: [] },
+        build: { values: ['env', 'repo', 'git-url', 'ref', 'path', 'out'], booleans: [] },
+        plan: { values: ['env', 'repo', 'git-url', 'ref', 'path'], booleans: [] },
+        deploy: { values: ['env', 'repo', 'git-url', 'ref', 'path', 'project', 'out'], booleans: ['skip-unchanged', 'no-create'] },
+        dev: { values: ['env', 'key', 'link', 'port'], booleans: ['once'] },
+        promote: { values: ['env'], booleans: [] }, pull: { values: ['env', 'out'], booleans: [] },
+        rollback: { values: ['env'], booleans: [] },
+    };
+    const { values, booleans } = options[args.command];
+    const allowed = new Set([...values, ...booleans]);
+    for (const key of Object.keys(args.flags)) {
+        if (!allowed.has(key)) {
+            return `Unknown option --${key} for artifact ${args.command}. Run seq-studio artifact --help.`;
+        }
+        if (values.includes(key) && (args.flags[key] === true || args.flags[key]?.trim() === '')) {
+            return `Option --${key} requires a value for artifact ${args.command}.`;
+        }
+        if (booleans.includes(key) && args.flags[key] !== true) {
+            return `Option --${key} does not take a value for artifact ${args.command}.`;
+        }
+    }
+    return undefined;
+}
 function parseArgs(argv) {
     if (argv[0] === '--')
         argv = argv.slice(1);
@@ -157,6 +195,7 @@ async function initCommand(args) {
         }
     }
     console.log(`[seq-studio] initialized ${dir}`);
+    console.log('AGENTS.md points to your environment\'s live docs; CLAUDE.md imports it.');
     console.log(template === 'nextjs'
         ? 'Next: cd into the app, run pnpm install, then seq-studio login && seq-studio artifact dev --env <env>. Commit pnpm-lock.yaml before deploying. No cloud credentials are required.'
         : 'Next: seq-studio login && seq-studio artifact dev --env <env>  (see: seq-studio envs list)');
@@ -272,6 +311,10 @@ async function listCommand(args) {
         token,
         path: '/api/artifact-studio/projects',
     });
+    if (args.flags.json === true) {
+        console.log(JSON.stringify(data, null, 2));
+        return 0;
+    }
     if (data.projects.length === 0) {
         console.log(`[seq-studio] no artifact projects visible on ${env.name}`);
         return 0;
@@ -325,6 +368,10 @@ async function showCommand(args) {
         console.error(`[seq-studio] project ${projectId} not found on ${env.name}`);
         return 1;
     }
+    if (args.flags.json === true) {
+        console.log(JSON.stringify(data, null, 2));
+        return 0;
+    }
     const project = data.project;
     console.log(`[seq-studio] project on ${env.name}:`);
     console.log(`  id:          ${project.id}`);
@@ -503,9 +550,14 @@ async function deployCommand(args) {
         // Fail closed before build / project create for deployed environments.
         // Local Atlas is a developer's own target, so it intentionally accepts
         // the current branch and dirty working tree.
-        if (env.name !== 'local')
-            assertActiveDeployProvenance(source.provenance);
-        if (isNextArtifactManifest(await readArtifactStudioManifest(source.dir))) {
+        if (env.name !== 'local') {
+            assertActiveDeployProvenance({ ...source.provenance, environment: env.name });
+        }
+        const manifest = await readArtifactStudioManifest(source.dir);
+        // After source resolution, so --repo / --git-url deploys check the fetched manifest.
+        warnOnRoleDefinitions(manifest);
+        await assertArtifactEnvironmentBindings({ directory: source.dir, environment: env, token });
+        if (isNextArtifactManifest(manifest)) {
             return await buildNextCommand({ args, source, active: true });
         }
         // --skip-unchanged: hash the raw source (no build needed) and no-op when
@@ -565,8 +617,9 @@ async function buildNextCommand({ args, source, active }) {
     const { nextSourceRepository, resolveNextRepositoryId, submitNextBuild } = await import('./next-build.js');
     const spec = parseSourceSpec(args);
     const repository = nextSourceRepository({ spec, root: source.dir });
-    if (active)
-        assertActiveDeployProvenance(source.provenance);
+    if (active) {
+        assertActiveDeployProvenance({ ...source.provenance, environment: env.name });
+    }
     const repositoryId = active || spec.kind === 'git-service'
         ? await resolveNextRepositoryId({ spec, repository, baseUrl: env.url, token })
         : undefined;
@@ -579,7 +632,7 @@ async function buildNextCommand({ args, source, active }) {
         console.log('[seq-studio] Next.js submits source to Atlas for build verification; local static-bundle skip checks do not apply.');
     }
     return submitNextBuild({
-        root: source.dir, manifest, projectId: project.id, baseUrl: env.url,
+        root: source.dir, sourceRoot: source.sourceRoot, manifest, projectId: project.id, baseUrl: env.url,
         getToken: () => getRequiredToken(args), provenance: source.provenance, repository, repositoryId,
         channel: active ? 'active' : 'preview', out: typeof args.flags.out === 'string' ? resolve(args.flags.out) : undefined,
     });

package/dist/deployment-validation.d.ts

@@ -7,3 +7,5 @@ export declare function authenticatedRequestUrl({ baseUrl, path, }: {
     baseUrl: string;
     path: string;
 }): string;
+export { assertNoCrossEnvironmentBindings, canonicalDeploymentOrigin, findCrossEnvironmentBindings, type BindingSourceFile, type CrossEnvironmentBinding, type NamedOrigin, type NamedWorkspace, } from './env-bindings.js';
+export { readArtifactStudioSource } from './project.js';

package/dist/deployment-validation.js

@@ -68,3 +68,5 @@ export function authenticatedRequestUrl({ baseUrl, path, }) {
     }
     return request.href;
 }
+export { assertNoCrossEnvironmentBindings, canonicalDeploymentOrigin, findCrossEnvironmentBindings, } from './env-bindings.js';
+export { readArtifactStudioSource } from './project.js';

package/dist/dev-link.js

@@ -3,12 +3,12 @@ import { createHash } from 'node:crypto';
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { cp, mkdir, readFile, readdir, rm } from 'node:fs/promises';
 import { createRequire } from 'node:module';
-import { dirname, join, relative, resolve } from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 /** True only when this dev session explicitly selected a local Atlas UI package. */
 export function hasLinkedAtlasUiToolchain({ deps }) {
     return deps.some((dep) => dep.name === '@sequenceholdings/atlas-ui');
 }
-const WATCHED_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.css', '.json']);
+const WATCHED_EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', '.css', '.json']);
 const IGNORED_DIRS = new Set(['node_modules', '.git', 'dist', '.next', '.turbo', '.cache']);
 const defaultResolver = createRequire(import.meta.url).resolve;
 /** Split a `--link a,b` flag value into trimmed, non-empty paths. */
@@ -168,6 +168,16 @@ export function rebuildLinkedDep(dep, signal, env) {
         });
     });
 }
+function exportsReferencePath(value, path) {
+    if (typeof value === 'string') {
+        const pattern = value.split('*').map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*');
+        return new RegExp('^' + pattern + '$').test(path);
+    }
+    if (value && typeof value === 'object') {
+        return Object.values(value).some((entry) => exportsReferencePath(entry, path));
+    }
+    return false;
+}
 /**
  * Copy a linked package's freshly built `dist` and root CSS entries into the
  * location the artifact build resolves them from. A no-op when the artifact
@@ -181,10 +191,26 @@ export async function syncLinkedDist(dep) {
         throw new Error(`${dep.name} build produced no dist at ${dep.distDir}`);
     }
     const targetPkgDir = dirname(dep.targetDistDir);
+    const targetManifest = join(targetPkgDir, 'package.json');
+    const targetExports = existsSync(targetManifest)
+        ? JSON.parse(await readFile(targetManifest, 'utf8')).exports
+        : undefined;
     await mkdir(targetPkgDir, { recursive: true });
     await rm(dep.targetDistDir, { recursive: true, force: true });
     await cp(dep.distDir, dep.targetDistDir, { recursive: true });
     for (const file of await packageRootCssFiles(dep.dir)) {
-        await cp(file, join(targetPkgDir, relative(dep.dir, file)));
+        // Published packages can export a compiled sheet from dist while the
+        // linked source package also keeps its generated source sheet at root.
+        // Copying both creates two candidates for the same subpath and violates
+        // the package contract. Only remove it when the installed exports map
+        // explicitly owns the dist path and no condition still needs the root.
+        const targetRootFile = join(targetPkgDir, relative(dep.dir, file));
+        if (existsSync(join(dep.distDir, basename(file))) &&
+            exportsReferencePath(targetExports, './dist/' + basename(file)) &&
+            !exportsReferencePath(targetExports, './' + basename(file))) {
+            await rm(targetRootFile, { force: true });
+            continue;
+        }
+        await cp(file, targetRootFile);
     }
 }

package/dist/env-binding-scan.d.ts

@@ -0,0 +1,10 @@
+import type { BindingSourceFile, NamedOrigin } from './env-bindings.js';
+export declare function originsDeclaredInFiles(files: readonly BindingSourceFile[]): NamedOrigin[];
+export declare function declaredTargets(content: string): Record<string, string>;
+export declare function contentContainsOrigin(content: string, origin: string, skippedLines: ReadonlySet<number>): boolean;
+/** Manifest text with the root `targets` map removed, so its URLs are declarations. */
+export declare function contentOutsideTargets(content: string): string;
+export declare function collectWorkspaceSlotIds(files: readonly BindingSourceFile[]): string[];
+export declare function workspaceSlotIds(file: BindingSourceFile): string[];
+export declare function scannable(file: BindingSourceFile): boolean;
+export declare function basename(path: string): string;