@sequenceholdings/artifact-studio 0.10.0 → 0.11.0

package/README.md

@@ -156,6 +156,41 @@ 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).
 
+## Lattice processes from a static app (awaiting publication)
+
+A static (React/Vite) artifact starts, reads and acts on Lattice runs with the
+same operations a Next.js server uses. Declare each process id in
+`artifact.bundle.yml`:
+
+```yaml
+capabilities:
+  processes:
+    start: [maintenance-request]   # start runs
+    read: [maintenance-request]    # list and show runs, describe the process, the user's own tasks
+    act: [maintenance-request]     # complete or reassign human steps, cancel, share runs
+```
+
+```ts
+import { createArtifactProcesses } from '@sequenceholdings/artifact-studio'
+
+const processes = createArtifactProcesses()
+const run = await processes.start({ process: 'maintenance-request', metadata: { unit: '4B' } })
+const snapshot = await processes.getRun(run.run_id)
+const tasks = await processes.listTasks()
+await processes.advance({ runId: run.run_id, payload: { approved: true } })
+```
+
+Atlas checks every call against the deployed manifest's `capabilities.processes`,
+not the browser's copy. A process it does not declare is refused with 403
+before any grant is checked; declaring `/api/lattice/runs` under
+`capabilities.api.write` is not a substitute, because that path is not scoped to
+a process. The signed-in user's own grants then decide: Invoker to start,
+Viewer to read, Advancer to complete a step, Owner to reassign or share.
+Refusals raise `ArtifactServerError`, with Atlas's `detail` and `code` on
+`error.atlas`. Group task pages, task assignments, batch describe and the
+human-completion readers stay Next.js-only. This needs the matching Atlas
+release; on an older host `createArtifactProcesses()` throws `processes_unavailable`.
+
 ## Lattice run lists and collaboration (internal prerelease)
 
 The server entry point remains an **internal** surface. These methods describe

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

@@ -20,6 +20,11 @@ export interface ActiveDeployProvenance {
     gitCommit?: string | null;
     gitBranch?: string | null;
     gitDirty?: boolean | null;
+    /**
+     * The target deployment's own environment (its Atlas `APP_ENV`). A CLI `-e`
+     * name is only a local alias (`sandbox` in an agent sandbox, or whatever
+     * `envs add` chose), so the CLI never supplies it.
+     */
     environment?: string | null;
 }
 /** Canonical default branch name for official artifact deploys. */
@@ -36,7 +41,15 @@ export declare function isActiveDeployDefaultBranch(branch: string | null | unde
 /** 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.
+ * Throw if provenance is not eligible for an official (active) deploy to the
+ * deployment named by `provenance.environment`. Preview callers must not
+ * invoke this.
  */
 export declare function assertActiveDeployProvenance(provenance: ActiveDeployProvenance): void;
+/**
+ * The CLI's check before it builds or uploads. Only Atlas knows whether the
+ * target deployment is a staging environment, so this admits `staging` and
+ * leaves that decision to Atlas, which repeats the full check with its own
+ * environment.
+ */
+export declare function assertActiveDeploySourceBeforeUpload(provenance: Omit<ActiveDeployProvenance, 'environment'>): void;

package/dist/active-deploy-policy.js

@@ -44,11 +44,31 @@ export function isStagingEnvironment(environment) {
     const normalized = environment?.trim().toLowerCase();
     return normalized === 'staging' || normalized?.endsWith('_staging') === true || normalized?.endsWith('-staging') === true;
 }
+/** The preview deploy an official-deploy refusal points at. */
+function previewHint(ref) {
+    return `Deploy it as a preview instead: \`seq-studio artifact deploy --repo <ns>/<name> --ref ${ref} --preview\``;
+}
 /**
- * Throw if provenance is not eligible for an official (active) deploy.
- * Preview callers must not invoke this.
+ * Throw if provenance is not eligible for an official (active) deploy to the
+ * deployment named by `provenance.environment`. Preview callers must not
+ * invoke this.
  */
 export function assertActiveDeployProvenance(provenance) {
+    assertOfficialSource({
+        provenance,
+        target: { staging: isStagingEnvironment(provenance.environment), environment: provenance.environment },
+    });
+}
+/**
+ * The CLI's check before it builds or uploads. Only Atlas knows whether the
+ * target deployment is a staging environment, so this admits `staging` and
+ * leaves that decision to Atlas, which repeats the full check with its own
+ * environment.
+ */
+export function assertActiveDeploySourceBeforeUpload(provenance) {
+    assertOfficialSource({ provenance, target: { staging: 'decided-by-atlas' } });
+}
+function assertOfficialSource({ provenance, target }) {
     // Require an explicit clean source-directory recording — omitting gitDirty
     // must not pass. The local source resolver scopes this value to the
     // artifact directory, so unrelated changes elsewhere in a containing
@@ -66,12 +86,16 @@ export function assertActiveDeployProvenance(provenance) {
             '`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.');
     }
-    const stagingBranchAllowed = branch === ACTIVE_DEPLOY_STAGING_BRANCH && isStagingEnvironment(provenance.environment);
-    if (branch !== ACTIVE_DEPLOY_DEFAULT_BRANCH && !stagingBranchAllowed) {
+    if (branch === ACTIVE_DEPLOY_STAGING_BRANCH && target.staging === false) {
+        const environment = target.environment?.trim();
+        throw new ActiveDeployPolicyError(`The \`${ACTIVE_DEPLOY_STAGING_BRANCH}\` branch deploys officially only to a staging deployment, ` +
+            `and this deployment${environment ? ` (\`${environment}\`)` : ''} is not one. ` +
+            `Deploy \`${ACTIVE_DEPLOY_DEFAULT_BRANCH}\` here. ${previewHint(branch)}`);
+    }
+    if (branch !== ACTIVE_DEPLOY_DEFAULT_BRANCH && branch !== ACTIVE_DEPLOY_STAGING_BRANCH) {
         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.');
+            `(or \`${ACTIVE_DEPLOY_STAGING_BRANCH}\` on a staging deployment); got branch/ref \`${branch}\`. ` +
+            `Merge it via a Pull, then redeploy from \`${ACTIVE_DEPLOY_DEFAULT_BRANCH}\`. ${previewHint(branch)}`);
     }
     if (!provenance.gitCommit?.trim()) {
         throw new ActiveDeployPolicyError('Active (official) artifact deploys require a resolved git commit on `main` ' +

package/dist/build.js

@@ -83,6 +83,12 @@ function createPeerResolveAlias({ atlasUiPackageDir = atlasUiDir } = {}) {
         '@tanstack/react-query': reactQueryDir,
         'react-router-dom': reactRouterDomDir,
         sonner: sonnerDir,
+        // The CLI pins the shared SDK just as it pins ORM/Storage. Explicit subpaths
+        // precede the package root because Vite aliases also match prefixes.
+        '@sequenceholdings/platform/browser': cliRequire.resolve('@sequenceholdings/platform/browser'),
+        '@sequenceholdings/platform/contracts': cliRequire.resolve('@sequenceholdings/platform/contracts'),
+        '@sequenceholdings/platform/storage': cliRequire.resolve('@sequenceholdings/platform/storage'),
+        '@sequenceholdings/platform': cliRequire.resolve('@sequenceholdings/platform'),
         '@sequenceholdings/storage': cliRequire.resolve('@sequenceholdings/storage'),
         '@sequenceholdings/orm/client': cliRequire.resolve('@sequenceholdings/orm/client'),
         '@sequenceholdings/artifact-studio/offline': offlineRuntimeEntry,

package/dist/cli.js

@@ -16,11 +16,12 @@ import { acquireDevLock } from './dev-lock.js';
 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 { assertActiveDeploySourceBeforeUpload } 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';
+import { branchPreviewKey } from './preview-key.js';
 const COMMANDS = [
     'init', 'whoami', 'link', 'env', 'status', 'list', 'show',
     'content-readers', 'validate', 'build', 'plan', 'deploy', 'dev', 'promote', 'pull', 'rollback',
@@ -37,6 +38,7 @@ const USAGE = `usage:
   seq-studio artifact build [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] [--path <dir>] [--source-env <env>] [--out dist/artifact-bundle.json]
   seq-studio artifact plan [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] [--path <dir>] [--source-env <env>] --env <env>
   seq-studio artifact deploy [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] [--path <dir>] [--source-env <env>] --env <env> [--skip-unchanged] [--no-create] [--project <id>]
+  seq-studio artifact deploy --repo <ns>/<name> --ref <branch> --preview [--key <key>] --env <env>
   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>
@@ -60,6 +62,15 @@ const USAGE = `usage:
   trees; feature branches and dirty source trees remain preview-only for
   deployed environments (\`artifact dev\` / preview channel).
 
+  A preview is a private test copy of the app. deploy --preview builds any
+  branch, tag, or commit and prints a link that opens it inside Atlas for people
+  who can edit the project; the live app and its users are unaffected. For a
+  static app each --key (default: the --ref name, else "default") keeps one
+  preview, replaced by the next deploy with that key. Each Next.js preview is
+  its own immutable build with its own link, so --key does not apply. A
+  preview is never promoted: merge the branch and deploy main (or staging) to
+  go live.
+
   Interactive --repo builds clone over smart-HTTP using your seq-studio login
   and repository read access. No PAT is needed. Headless M2M builds use JSON
   materialize and accept only platform-managed --repo sources. Use --env to
@@ -127,7 +138,7 @@ function validateKnownOptions(args) {
         show: { values: ['env'], booleans: ['json'] }, validate: { values: [], booleans: [] },
         build: { values: ['source-env', 'env', 'repo', 'git-url', 'ref', 'path', 'out'], booleans: [] },
         plan: { values: ['source-env', 'env', 'repo', 'git-url', 'ref', 'path'], booleans: [] },
-        deploy: { values: ['source-env', 'env', 'repo', 'git-url', 'ref', 'path', 'project', 'out'], booleans: ['skip-unchanged', 'no-create'] },
+        deploy: { values: ['source-env', 'env', 'repo', 'git-url', 'ref', 'path', 'project', 'out', 'key'], booleans: ['skip-unchanged', 'no-create', 'preview'] },
         dev: { values: ['env', 'key', 'link', 'port'], booleans: ['once'] },
         promote: { values: ['env'], booleans: [] }, pull: { values: ['env', 'out'], booleans: [] },
         rollback: { values: ['env'], booleans: [] },
@@ -565,6 +576,7 @@ async function planCommand(args) {
     }
 }
 async function deployCommand(args) {
+    const preview = isPreviewDeploy(args);
     const env = await envFromArgs(args);
     const auth = await getRequiredAuth(args);
     const { token } = auth;
@@ -580,16 +592,19 @@ async function deployCommand(args) {
     try {
         // 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, environment: env.name });
+        // the current branch and dirty working tree. A preview accepts any ref.
+        if (env.name !== 'local' && !preview) {
+            assertActiveDeploySourceBeforeUpload(source.provenance);
         }
         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 });
+            if (preview && args.flags.key !== undefined) {
+                throw new Error('--key names a static preview. Each Next.js preview is its own immutable build with its own link; omit --key.');
+            }
+            return await buildNextCommand({ args, source, active: !preview });
         }
         assertSourceEnvironmentSupportsManifest(args);
         // --skip-unchanged: hash the raw source (no build needed) and no-op when
@@ -631,6 +646,8 @@ async function deployCommand(args) {
             allowCreate: args.flags['no-create'] !== true,
             explicitProjectId,
         });
+        if (preview)
+            return await uploadPreview({ args, envUrl: env.url, token, project, result, provenance: source.provenance });
         const deployment = await uploadDeployment({ env: env.url, token, projectId: project.id, result, channel: 'active', provenance: source.provenance });
         console.log(`[seq-studio] deployed ${project.title} ${deployment.version}`);
         console.log(`${env.url}/artifact-studio/projects/${project.id}/deployments/${deployment.id}`);
@@ -640,6 +657,25 @@ async function deployCommand(args) {
         await source.cleanup();
     }
 }
+/** `deploy --preview`: any ref, never the live app. --key belongs to it, --skip-unchanged does not. */
+function isPreviewDeploy(args) {
+    const preview = args.flags.preview === true;
+    if (!preview && args.flags.key !== undefined)
+        throw new Error('--key names a preview; add --preview, or omit --key for an official deploy.');
+    if (preview && args.flags['skip-unchanged'] === true)
+        throw new Error('--skip-unchanged compares against the official deployment; it does not apply to --preview.');
+    return preview;
+}
+async function uploadPreview({ args, envUrl, token, project, result, provenance }) {
+    const previewKey = branchPreviewKey({ key: args.flags.key, ref: args.flags.ref });
+    const deployment = await uploadDeployment({
+        env: envUrl, token, projectId: project.id, result, channel: 'preview', previewKey, provenance,
+        message: `Preview of ${provenance.gitBranch ?? provenance.gitCommit?.slice(0, 12) ?? 'local source'}`,
+    });
+    console.log(`[seq-studio] preview ${deployment.version} of ${project.title} (key ${previewKey}); the live app is unchanged`);
+    console.log(`${envUrl}/artifact-studio/projects/${project.id}/preview?key=${encodeURIComponent(previewKey)}`);
+    return 0;
+}
 async function buildNextCommand({ args, source, active }) {
     const env = await envFromArgs(args);
     const token = await getRequiredToken(args);
@@ -650,7 +686,7 @@ async function buildNextCommand({ args, source, active }) {
     const spec = parseSourceSpec(args);
     const repository = nextSourceRepository({ spec, root: source.dir });
     if (active) {
-        assertActiveDeployProvenance({ ...source.provenance, environment: env.name });
+        assertActiveDeploySourceBeforeUpload(source.provenance);
     }
     const sourceEnvironment = sourceEnvironmentFromArgs(args);
     const sourceToken = sourceEnvironment ? (await getSourceAuth(args)).token : token;

package/dist/manifest-static.d.ts

@@ -77,6 +77,11 @@ export declare const artifactStudioStaticManifestSchema: z.ZodObject<{
         functions: z.ZodDefault<z.ZodObject<{
             invoke: z.ZodDefault<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
+        processes: z.ZodDefault<z.ZodObject<{
+            start: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            act: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
         allow_downloads: z.ZodDefault<z.ZodBoolean>;
         allow_popups: z.ZodDefault<z.ZodBoolean>;
         roles: z.ZodOptional<z.ZodObject<{

package/dist/manifest-static.js

@@ -3,6 +3,7 @@ import { ontologyContractSchema } from '@sequenceholdings/orm/canonical';
 import { z } from 'zod';
 import { capabilityPinsSchema, customRolesBlockSchema, validateCapabilityPins, } from './manifest-custom-roles.js';
 import { normalizeArtifactPath } from './paths.js';
+import { latticeProcessRef } from './manifest-next-reach.js';
 export { CUSTOM_CAPABILITY_PIN_RE, CUSTOM_ROLE_KEY_RE, capabilityPinsSchema, customRolesBlockSchema, customRolesDeclared, parseCapabilityPin, validateCapabilityPins, } from './manifest-custom-roles.js';
 const apiCapabilityPathSchema = z.string().min(1).refine((path) => path.startsWith('/api/') && path !== '/api/' && path !== '/api/*', 'API capability paths must be scoped below /api/');
 const apiCapabilitiesSchema = z.object({
@@ -91,6 +92,18 @@ export const artifactStudioStaticManifestSchema = z.object({
         functions: z.object({
             invoke: z.array(z.string().min(1)).default([]),
         }).default({ invoke: [] }),
+        /**
+         * Lattice processes `createArtifactProcesses()` may reach, as in a Next.js
+         * manifest: `start` runs of, `read` runs, templates and the user's own steps
+         * of, and `act` on (complete or reassign human steps, cancel, share runs).
+         * Exact process ids; Atlas checks them against the deployed manifest, then
+         * the user's own Invoker / Viewer / Advancer / Owner grants decide.
+         */
+        processes: z.object({
+            start: z.array(latticeProcessRef).max(256).default([]),
+            read: z.array(latticeProcessRef).max(256).default([]),
+            act: z.array(latticeProcessRef).max(256).default([]),
+        }).default({ start: [], read: [], act: [] }),
         /** Opt-in: enables iframe `allow-downloads`. Default false. */
         allow_downloads: z.boolean().default(false),
         /**
@@ -117,6 +130,7 @@ export const artifactStudioStaticManifestSchema = z.object({
         data: { read: [], write: [] },
         api: { read: [], write: [] },
         functions: { invoke: [] },
+        processes: { start: [], read: [], act: [] },
         allow_downloads: false,
         allow_popups: false,
         uses: [],

package/dist/manifest.d.ts

@@ -48,6 +48,11 @@ export declare const artifactStudioManifestSchema: z.ZodUnion<readonly [z.ZodObj
         functions: z.ZodDefault<z.ZodObject<{
             invoke: z.ZodDefault<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
+        processes: z.ZodDefault<z.ZodObject<{
+            start: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            act: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
         allow_downloads: z.ZodDefault<z.ZodBoolean>;
         allow_popups: z.ZodDefault<z.ZodBoolean>;
         roles: z.ZodOptional<z.ZodObject<{