@sequenceholdings/artifact-studio 0.2.5 → 0.3.0

package/README.md

@@ -0,0 +1,35 @@
+# Artifact Studio SDK
+
+`@sequenceholdings/artifact-studio` exposes the host-provided `seq` client. Runtime
+requests use the current user's normal permissions.
+
+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).
+
+## Grouping calls into a trace
+
+The Artifact host supplies tracing context automatically for supported platform
+requests. Use an explicit action scope to correlate several calls from one UI
+action and supply a readable intent key:
+
+```ts
+import { withTraceAction } from '@sequenceholdings/artifact-studio'
+
+await withTraceAction(
+  { key: 'application.refresh' },
+  async ({ api, functions }) => {
+    await functions.invoke('my-function', { refresh: true })
+    await api.get('/api/my-application/summary')
+  },
+)
+```
+
+Use a stable operation label, never an identifier, customer value or payload. Each
+scope gets its own correlation ID, so concurrent actions remain separate. The
+helper scopes JSON `api.fetch/get/post/put/patch/delete` and `functions.invoke`;
+streaming and file-transfer helpers retain their ordinary host tracing behavior.
+Tracing does not grant permissions, change service-account behavior or guarantee
+that every transport is instrumented. Traces availability depends on the deployed
+platform version and your app/resource permissions.

package/VERSION-PIN.md

@@ -4,12 +4,19 @@ A (re)built Artifact Studio app gets whatever `@sequenceholdings/atlas-ui` the
 **building CLI** carries — not a semver the artifact's own `package.json`
 declares.
 
-Artifact Studio 0.2.5 (Studio CLI 0.1.31) pins Atlas UI 3.1.2 exactly.
+Artifact Studio 0.2.7 (Studio CLI 0.1.36) pins Atlas UI 3.3.0 exactly.
 Ordinary builds now use its canonical, mode-aware `tokens.css`. Rebuilding an
 existing artifact adopts this toolchain; previously uploaded immutable bundles
 keep their original CSS. Migrate retired numbered black/white utilities to
 semantic roles and verify a preview before activating a rebuilt artifact.
 
+Artifact Studio 0.3.0 (Studio CLI 0.2.0) adds the opt-in Next.js runtime. The
+static compiler continues to pin Atlas UI 3.3.0. Next.js applications own their
+React 19 dependencies and use the `/next` client boundary that Atlas UI 3.4.0
+introduces; they do not inherit the static compiler's aliases. The new packages must be published
+before a fresh external Next.js scaffold can be installed. A local candidate
+build is not evidence of registry availability.
+
 ## What this means
 
 `shared/services/artifact-studio/src/build.ts` force-aliases platform peers via
@@ -53,8 +60,12 @@ never claims `no-op` for a deploy that would actually rebuild.
 
 `tokens.css` is the canonical stylesheet and includes semantic roles plus the
 Tailwind utility bridge. The legacy `tokens.v2.css` and `theme.v2.css` paths are
-temporary forwarding aliases; the compiler normalizes their source imports to one
-canonical layer and reports a migration warning. An explicit
+temporary forwarding aliases in current packages; the compiler normalizes their
+source imports to one canonical layer and reports a migration warning only after
+checking that both selected files are forwarding aliases. Older packages carry
+independent styles in those files, so their imports and provenance entries are
+preserved. This prevents CRM spacing and corner utilities from disappearing when
+rebuilding with a split-sheet package. An explicit
 `seq-studio artifact dev --link <atlas-ui-package-dir>` preview additionally
 reports retired numbered black/white opacity utilities and uncertain dynamic
 class construction. Legacy stylesheet aliases normalize to canonical tokens;

package/dist/api.d.ts

@@ -2,13 +2,23 @@ export interface ApiClientOptions {
     baseUrl: string;
     token: string;
 }
+export declare class ArtifactApiError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
 export declare function getJson<T>({ baseUrl, token, path }: ApiClientOptions & {
     path: string;
 }): Promise<T>;
 export declare function getJsonOr404<T>({ baseUrl, token, path }: ApiClientOptions & {
     path: string;
 }): Promise<T | null>;
-export declare function postJson<T>({ baseUrl, token, path, body, }: ApiClientOptions & {
+export declare function postJson<T>({ baseUrl, token, path, body, retry503, signal, }: ApiClientOptions & {
     path: string;
     body?: unknown;
+    retry503?: boolean;
+    signal?: AbortSignal;
 }): Promise<T>;
+export declare function deleteJson({ baseUrl, token, path, signal }: ApiClientOptions & {
+    path: string;
+    signal?: AbortSignal;
+}): Promise<void>;

package/dist/api.js

@@ -1,4 +1,13 @@
+import { setTimeout as delay } from 'node:timers/promises';
 import { authenticatedRequestUrl } from './deployment-validation.js';
+export class ArtifactApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'ArtifactApiError';
+    }
+}
 const MAX_503_RETRIES = 5;
 const DEFAULT_RETRY_AFTER_SECONDS = 2;
 /**
@@ -36,19 +45,20 @@ function extraHeaders() {
         return {};
     }
 }
-async function fetchWith503Retry(input, init) {
+async function fetchWith503Retry(input, init, maxRetries = MAX_503_RETRIES) {
     let attempt = 0;
     while (true) {
         const response = await fetch(input, init);
-        if (response.status !== 503 || attempt >= MAX_503_RETRIES)
+        if (response.status !== 503 || attempt >= maxRetries)
             return response;
         const retryAfter = Number(response.headers.get('Retry-After')) || DEFAULT_RETRY_AFTER_SECONDS;
         attempt += 1;
         console.warn(`[seq-studio] backend warming up (503); retrying in ${retryAfter}s (attempt ${attempt}/${MAX_503_RETRIES})`);
-        await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
+        // An aborted caller (e.g. artifact dev shutting down) must not wait out a Retry-After.
+        await delay(retryAfter * 1000, undefined, init.signal ? { signal: init.signal } : undefined);
     }
 }
-async function authenticatedFetch({ baseUrl, init = {}, path, token, }) {
+async function authenticatedFetch({ baseUrl, init = {}, path, token, retry503 = true, }) {
     const url = authenticatedRequestUrl({ baseUrl, path });
     return fetchWith503Retry(url, {
         ...init,
@@ -58,12 +68,12 @@ async function authenticatedFetch({ baseUrl, init = {}, path, token, }) {
             ...init.headers,
             Authorization: `Bearer ${token}`,
         },
-    });
+    }, retry503 ? MAX_503_RETRIES : 0);
 }
 export async function getJson({ baseUrl, token, path }) {
     const response = await authenticatedFetch({ baseUrl, token, path });
     if (!response.ok)
-        throw new Error(await responseError('GET', path, response));
+        throw new ArtifactApiError(await responseError('GET', path, response), response.status);
     return response.json();
 }
 export async function getJsonOr404({ baseUrl, token, path }) {
@@ -71,24 +81,31 @@ export async function getJsonOr404({ baseUrl, token, path }) {
     if (response.status === 404)
         return null;
     if (!response.ok)
-        throw new Error(await responseError('GET', path, response));
+        throw new ArtifactApiError(await responseError('GET', path, response), response.status);
     return response.json();
 }
-export async function postJson({ baseUrl, token, path, body, }) {
+export async function postJson({ baseUrl, token, path, body, retry503 = true, signal, }) {
     const response = await authenticatedFetch({
         baseUrl,
         token,
         path,
+        retry503,
         init: {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: body === undefined ? undefined : JSON.stringify(body),
+            ...(signal ? { signal } : {}),
         },
     });
     if (!response.ok)
-        throw new Error(await responseError('POST', path, response));
+        throw new ArtifactApiError(await responseError('POST', path, response), response.status);
     return response.json();
 }
+export async function deleteJson({ baseUrl, token, path, signal }) {
+    const response = await authenticatedFetch({ baseUrl, token, path, init: { method: 'DELETE', ...(signal ? { signal } : {}) } });
+    if (!response.ok)
+        throw new ArtifactApiError(await responseError('DELETE', path, response), response.status);
+}
 /**
  * Build an actionable error message from a failed response: which request
  * failed, with what status, and what the server said. A deploy runs several

package/dist/atlas-ui-css-plugin.d.ts

@@ -1,11 +1,15 @@
 import type { Plugin } from 'vite';
 export interface AtlasUiResolvedTokenSelection {
-    specifier: '@sequenceholdings/atlas-ui/tokens.css';
+    specifier: string;
     injectedBy: string | null;
 }
+/** Only collapse aliases when the selected package makes them forwarding sheets.
+ * Older releases define independent semantic tokens and the Tailwind bridge there.
+ */
+export declare function hasUnifiedAtlasUiTokens(atlasUiDir: string): boolean;
 /**
- * Every supported source shape becomes one canonical import before Tailwind
- * expands it. The aliases remain package-compatible, but are no longer allowed
+ * For packages with forwarding aliases, collapse imports before Tailwind
+ * expands them. The aliases remain package-compatible, but are no longer allowed
  * to create duplicate token layers in an Artifact Studio bundle (DES-437).
  */
 export declare function normalizeAtlasUiTokenImports(code: string): {
@@ -13,10 +17,10 @@ export declare function normalizeAtlasUiTokenImports(code: string): {
     deprecatedImports: string[];
 };
 /**
- * Evidence mirrors the CSS transform: aliases are normalized away, so the only
- * selected sheet is the canonical token entry point.
+ * Evidence mirrors the selected package: split sheets remain separate entries;
+ * forwarding aliases are normalized to the canonical entry point.
  */
-export declare function collectAtlasUiResolvedTokenSelections({ cssModules, }: {
+export declare function collectAtlasUiResolvedTokenSelections({ cssModules, atlasUiDir, }: {
     cssModules: readonly {
         id: string;
         code: string;
@@ -25,7 +29,7 @@ export declare function collectAtlasUiResolvedTokenSelections({ cssModules, }: {
     atlasUiDist: string;
     formRendererDist: string | null;
 }): AtlasUiResolvedTokenSelection[];
-export declare function atlasUiCssResolverPlugin({ atlasUiDir: _atlasUiDir, atlasUiDist, formRendererDist, onTransform, }: {
+export declare function atlasUiCssResolverPlugin({ atlasUiDir, atlasUiDist, formRendererDist, onTransform, }: {
     atlasUiDir: string;
     atlasUiDist: string;
     formRendererDist: string | null;

package/dist/atlas-ui-css-plugin.js

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -19,14 +19,26 @@ function resolveTwAnimateCssPath() {
 }
 const CANONICAL_TOKEN_IMPORT = '@import "@sequenceholdings/atlas-ui/tokens.css";';
 const ATLAS_UI_TOKEN_IMPORT = /@import\s+(?:url\(\s*)?(?:["'][^"']*?@sequenceholdings\/atlas-ui\/|[^"'()\s;]*@sequenceholdings\/atlas-ui\/)(tokens\.css|tokens\.v2\.css|theme\.v2\.css)(?:["'])?\s*\)?[^;\n]*;/gi;
+/** Only collapse aliases when the selected package makes them forwarding sheets.
+ * Older releases define independent semantic tokens and the Tailwind bridge there.
+ */
+export function hasUnifiedAtlasUiTokens(atlasUiDir) {
+    return ['tokens.v2.css', 'theme.v2.css'].every((sheet) => {
+        const path = resolve(atlasUiDir, sheet);
+        if (!existsSync(path))
+            return false;
+        const content = readFileSync(path, 'utf8').replace(/\/\*[\s\S]*?\*\//g, '').trim();
+        return /^@import\s+["']@sequenceholdings\/atlas-ui\/tokens\.css["'];$/.test(content);
+    });
+}
 function atlasUiTokenImportSheets(code) {
     return [...code.matchAll(ATLAS_UI_TOKEN_IMPORT)]
         .map((match) => match[1]?.toLowerCase())
         .filter((sheet) => sheet !== undefined);
 }
 /**
- * Every supported source shape becomes one canonical import before Tailwind
- * expands it. The aliases remain package-compatible, but are no longer allowed
+ * For packages with forwarding aliases, collapse imports before Tailwind
+ * expands them. The aliases remain package-compatible, but are no longer allowed
  * to create duplicate token layers in an Artifact Studio bundle (DES-437).
  */
 export function normalizeAtlasUiTokenImports(code) {
@@ -43,16 +55,23 @@ export function normalizeAtlasUiTokenImports(code) {
     };
 }
 /**
- * Evidence mirrors the CSS transform: aliases are normalized away, so the only
- * selected sheet is the canonical token entry point.
+ * Evidence mirrors the selected package: split sheets remain separate entries;
+ * forwarding aliases are normalized to the canonical entry point.
  */
-export function collectAtlasUiResolvedTokenSelections({ cssModules, }) {
+export function collectAtlasUiResolvedTokenSelections({ cssModules, atlasUiDir, }) {
     for (const { code } of cssModules) {
         if (!code.includes('@import "tailwindcss"'))
             continue;
+        const sheets = atlasUiTokenImportSheets(code);
+        if (!hasUnifiedAtlasUiTokens(atlasUiDir)) {
+            return [...new Set(['tokens.css', ...sheets])].map((sheet) => ({
+                specifier: `@sequenceholdings/atlas-ui/${sheet}`,
+                injectedBy: sheets.includes(sheet) ? null : 'atlas-ui-css-resolver',
+            }));
+        }
         return [{
                 specifier: '@sequenceholdings/atlas-ui/tokens.css',
-                injectedBy: atlasUiTokenImportSheets(code).includes('tokens.css') ? null : 'atlas-ui-css-resolver',
+                injectedBy: sheets.includes('tokens.css') ? null : 'atlas-ui-css-resolver',
             }];
     }
     return [];
@@ -70,7 +89,8 @@ function insertAfterImports(code, lines) {
     const end = lastImport.index + lastImport[0].length;
     return `${code.slice(0, end)}${block}${code.slice(end)}`;
 }
-export function atlasUiCssResolverPlugin({ atlasUiDir: _atlasUiDir, atlasUiDist, formRendererDist, onTransform, }) {
+export function atlasUiCssResolverPlugin({ atlasUiDir, atlasUiDist, formRendererDist, onTransform, }) {
+    const unifiedTokens = hasUnifiedAtlasUiTokens(atlasUiDir);
     return {
         name: 'atlas-ui-css-resolver',
         enforce: 'pre',
@@ -88,8 +108,16 @@ export function atlasUiCssResolverPlugin({ atlasUiDir: _atlasUiDir, atlasUiDist,
                 if (formRendererDist) {
                     sources.push(`@source ${JSON.stringify(formRendererDist)};`);
                 }
-                const tokenImports = normalizeAtlasUiTokenImports(result);
-                result = tokenImports.code;
+                if (unifiedTokens) {
+                    result = normalizeAtlasUiTokenImports(result).code;
+                }
+                else if (!atlasUiTokenImportSheets(result).includes('tokens.css')) {
+                    const firstTokenImport = result.match(ATLAS_UI_TOKEN_IMPORT)?.[0];
+                    // The old base must precede the semantic overrides in split packages.
+                    result = firstTokenImport
+                        ? result.replace(firstTokenImport, `${CANONICAL_TOKEN_IMPORT}\n${firstTokenImport}`)
+                        : insertAfterImports(result, [CANONICAL_TOKEN_IMPORT]);
+                }
                 result = insertAfterImports(result, sources);
             }
             if (result.includes('@import "tw-animate-css"')) {

package/dist/build.d.ts

@@ -1,6 +1,6 @@
 import { type ObservedBuildEvidence } from './build-provenance.js';
 import { type ArtifactStudioSourceFile } from './project.js';
-import type { ArtifactStudioManifest } from './manifest.js';
+import { type ArtifactStudioStaticManifest } from './manifest.js';
 import { type ArtifactStudioPeerVersions } from './peer-versions.js';
 /**
  * Released Atlas UI 2.0.1 exports its canonical sheet from dist, while the
@@ -17,7 +17,7 @@ export interface ArtifactStudioRuntimeChunk {
 }
 export type ArtifactStudioBundleFormat = 'esm';
 export interface ArtifactStudioBuildResult {
-    manifest: ArtifactStudioManifest;
+    manifest: ArtifactStudioStaticManifest;
     files: ArtifactStudioSourceFile[];
     /** Entry module (ESM). Lazy routes land in `chunks`. */
     bundle: string;

package/dist/build.js

@@ -3,13 +3,14 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { dirname, relative, resolve } from 'node:path';
 import { build as viteBuild } from 'vite';
-import { atlasUiCssResolverPlugin, collectAtlasUiResolvedTokenSelections } from './atlas-ui-css-plugin.js';
+import { atlasUiCssResolverPlugin, collectAtlasUiResolvedTokenSelections, hasUnifiedAtlasUiTokens } from './atlas-ui-css-plugin.js';
 import { validateAtlasUiTokenStylesheetContract } from './atlas-ui-package-contract.js';
 import { createObservedBuildEvidence } from './build-provenance.js';
 import { collectResolvedStylesheets } from './resolved-stylesheets.js';
 import { sha256Hex } from './hash.js';
 import { isArtifactIgnoredPath } from './artifact-ignore.js';
 import { readArtifactStudioSource } from './project.js';
+import { isNextArtifactManifest } from './manifest.js';
 import { normalizeArtifactPath } from './paths.js';
 import { resolveArtifactStudioPeerVersions, } from './peer-versions.js';
 import { ARTIFACT_RUNTIME_CHUNK_DIR, assertSafeRuntimeChunkFileName } from './runtime-chunks.js';
@@ -31,6 +32,7 @@ const reactRouterDomDir = dirname(cliRequire.resolve('react-router-dom/package.j
 const sonnerDir = dirname(cliRequire.resolve('sonner'));
 const atlasUiDir = dirname(cliRequire.resolve('@sequenceholdings/atlas-ui/package.json'));
 const atlasUiDist = resolve(atlasUiDir, 'dist');
+const artifactSdkEntry = cliRequire.resolve('@sequenceholdings/artifact-studio');
 /**
  * Released Atlas UI 2.0.1 exports its canonical sheet from dist, while the
  * candidate layout puts the generated entry at package root so it can be read
@@ -75,6 +77,7 @@ function createPeerResolveAlias({ atlasUiPackageDir = atlasUiDir } = {}) {
         '@tanstack/react-query': reactQueryDir,
         'react-router-dom': reactRouterDomDir,
         sonner: sonnerDir,
+        '@sequenceholdings/storage': cliRequire.resolve('@sequenceholdings/storage'),
         // 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.
@@ -101,8 +104,13 @@ export async function buildArtifactStudioProject(rootDir, { candidateTokenCompat
     const selectedAtlasUiDist = resolve(atlasUiPackageDir ?? atlasUiDir, 'dist');
     const selectedAtlasUiTokens = resolveAtlasUiTokensPath(selectedAtlasUiDir);
     const source = await readArtifactStudioSource(rootDir);
+    if (isNextArtifactManifest(source.manifest)) {
+        throw new Error('Next.js applications are built by Atlas. Run seq-studio artifact build --env <env>.');
+    }
     const diagnostics = [
-        ...collectDeprecatedTokenImportDiagnostics({ files: source.files }),
+        ...(hasUnifiedAtlasUiTokens(selectedAtlasUiDir)
+            ? collectDeprecatedTokenImportDiagnostics({ files: source.files })
+            : []),
         ...(candidateTokenCompatibility
             ? collectCandidateTokenCompatibilityDiagnostics({ files: source.files })
             : []),
@@ -116,7 +124,7 @@ export async function buildArtifactStudioProject(rootDir, { candidateTokenCompat
         plugins: [
             rejectOutsideSourcePlugin({
                 root,
-                trustedExternalRoots: Object.values(peerResolveAlias).map((target) => dirname(target)),
+                trustedExternalRoots: [...Object.values(peerResolveAlias).map((target) => dirname(target)), dirname(artifactSdkEntry)],
             }),
             rejectIgnoredSourcePlugin(root, source.ignorePatterns),
             artifactSdkVirtualModule(),
@@ -267,8 +275,8 @@ function artifactSdkVirtualModule() {
         // host-injected `window.seq`, so a tree that happens to be `pnpm install`ed
         // must produce the same bundle as a bare tree (e.g. one materialized from a
         // git repo) — otherwise the same source yields different bytes depending on
-        // whether node_modules exists. The package's sole runtime export is `seq`
-        // (everything else is type-only), so this stub is a complete substitute.
+        // whether node_modules exists. Use the CLI's SDK entry so runtime helpers
+        // stay in sync with the types instead of maintaining a partial export stub.
         enforce: 'pre',
         resolveId(id) {
             return virtualIds.has(id) ? resolved : undefined;
@@ -276,7 +284,7 @@ function artifactSdkVirtualModule() {
         load(id) {
             if (id !== resolved)
                 return undefined;
-            return 'export const seq = window.seq; export default window.seq;';
+            return `export * from ${JSON.stringify(artifactSdkEntry)}; export { default } from ${JSON.stringify(artifactSdkEntry)};`;
         },
     };
 }

package/dist/cli.d.ts

@@ -5,7 +5,7 @@ interface RemoteProject {
     id: string;
     slug: string;
     title: string;
-    visibility?: string;
+    projectType?: string;
     activeDeployment?: {
         version: string;
         sourceHash: string;