@storystick/source 0.0.0-stage → 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,112 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Tanguy Freycon
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+This Agreement shall be governed by the laws of France.

package/PUBLIC-API.md

@@ -0,0 +1,19 @@
+# @storystick/source API contract
+
+Install this candidate explicitly with `@storystick/source@0.1.0-rc.1` after registry bootstrap and publication. This repository alone does not make the candidate or beta channel available on npm.
+
+Version 0.1.0-rc.1, cohort `sdk-0.2.0-rc.1`. ESM distribution; no CommonJS or universal Edge compatibility is promised.
+
+This package supports the integration facades; installing it directly is an advanced use. Reserved contracts are required between SDK packages and must be upgraded with the same cohort. Their public export paths do not promise independent stability.
+
+| Entry | Status |
+| --- | --- |
+| `./manifest` | Supported beta entry |
+| `./archive` | Supported beta entry |
+| `./recipe` | Supported beta entry |
+
+The qualified toolchain is Node 24.19.0 and pnpm 9.15.9. Next uses App Router 15.5.28, Sharp 0.35.5 and React/React DOM 19.2.8; Astro uses 7.4.4 with the Node adapter 11.1.9. Browser delivery is verified by bundling; hosted Preview activation and cross-browser behavior require the staging manual check. Source/CLI are Node tools, server entries belong on the server, and browser entries must never receive a server API key.
+
+This is a support/tooling contract. It does not independently grant project access or permission to perform effects.
+
+The repository is private. Public package availability does not make the monorepo public, and npm provenance from that repository is unavailable. Product and pilot support: [Storystick](https://storystick.app).

package/README.md

@@ -1,3 +1,20 @@
-# Temporary Holding Version
+# @storystick/source
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Source manifests, deterministic archives and execution-recipe validation shared by the Storystick CLI and workspace services. This ESM package targets Node.js.
+
+Import the supported entry points:
+
+```ts
+import { workspaceRecipe } from '@storystick/source/recipe'
+import { encodeSourceArchive, sourceDigest } from '@storystick/source/archive'
+```
+
+`@storystick/source/manifest` defines source paths and scopes. Archive helpers preserve content digests; recipe validation describes commands and does not execute or authorize them. Callers remain responsible for access checks, resource admission and execution isolation.
+
+License: FSL-1.1-MIT; see LICENSE distributed with this package.
+
+## Candidate distribution contract
+
+See [PUBLIC-API.md](./PUBLIC-API.md) for supported entries, reserved SDK contracts,
+the qualified runtime matrix and the candidate cohort. Upgrade Storystick
+packages together.

package/dist/archive.d.ts

@@ -0,0 +1,24 @@
+export { sourceManifest } from './manifest.js';
+export type SourceEntry = {
+    path: string;
+    content: Buffer;
+    mode: number;
+    digest: string;
+};
+export declare const sourceDigest: (value: string | Uint8Array) => string;
+export declare const sourceRevision: (files: SourceEntry[]) => string;
+/** Parse before uploading anything. No tar subprocess can reinterpret an unchecked header. */
+export declare function validateWorkspaceArchive(archive: Buffer, archiveDigest: string): SourceEntry[];
+/** A portable source checkpoint. Dependencies/build caches remain provider caches.
+ * Paths, modes and bytes (including binary assets) survive without a Git host. */
+export declare function encodeTar(files: {
+    path: string;
+    content: Buffer;
+    mode: number;
+}[]): Buffer<ArrayBuffer>;
+export declare function encodeSourceArchive(files: SourceEntry[]): NonSharedBuffer;
+export declare function editSource(files: SourceEntry[], input: {
+    file: string;
+    expectedDigest: string | null;
+    text: string;
+}): SourceEntry[];

package/dist/archive.js

@@ -0,0 +1,171 @@
+import { createHash } from 'node:crypto';
+import { gzipSync, gunzipSync } from 'node:zlib';
+import { posix } from 'node:path';
+import { sourcePath, sourceIdentity, sourceManifest, MAX_ARCHIVE_BYTES, MAX_SOURCE_BYTES, MAX_SOURCE_FILES } from './manifest.js';
+export { sourceManifest } from './manifest.js';
+export const sourceDigest = (value) => createHash('sha256').update(value).digest('hex');
+export const sourceRevision = (files) => sourceDigest(sourceIdentity(files));
+const DIGEST = /^[a-f0-9]{64}$/;
+const hash = sourceDigest;
+function fail(code) { throw Error(code); }
+function octal(bytes) {
+    const text = bytes.toString('ascii').replace(/\0.*$/, '').trim();
+    if (!/^[0-7]*$/.test(text))
+        fail('WORKSPACE_ARCHIVE_INVALID');
+    const n = text ? Number.parseInt(text, 8) : 0;
+    if (!Number.isSafeInteger(n) || n < 0)
+        fail('WORKSPACE_ARCHIVE_INVALID');
+    return n;
+}
+function tarText(bytes) { return bytes.toString('utf8').replace(/\0.*$/, ''); }
+function pax(data) {
+    const fields = {};
+    let offset = 0;
+    while (offset < data.length) {
+        const space = data.indexOf(32, offset);
+        const digits = data.subarray(offset, space).toString('ascii');
+        if (space < offset || !/^[1-9][0-9]*$/.test(digits))
+            fail('WORKSPACE_ARCHIVE_INVALID');
+        const length = Number(digits);
+        if (!Number.isSafeInteger(length) || length <= space - offset + 1 || offset + length > data.length || data[offset + length - 1] !== 10)
+            fail('WORKSPACE_ARCHIVE_INVALID');
+        const line = data.subarray(space + 1, offset + length - 1).toString('utf8');
+        const eq = line.indexOf('=');
+        if (eq <= 0)
+            fail('WORKSPACE_ARCHIVE_INVALID');
+        const key = line.slice(0, eq);
+        if (!['path', 'mtime', 'atime', 'ctime', 'comment', 'uid', 'gid', 'uname', 'gname'].includes(key))
+            fail('WORKSPACE_ARCHIVE_METADATA_UNSUPPORTED');
+        fields[key] = line.slice(eq + 1);
+        offset += length;
+    }
+    return fields;
+}
+/** Parse before uploading anything. No tar subprocess can reinterpret an unchecked header. */
+export function validateWorkspaceArchive(archive, archiveDigest) {
+    if (!DIGEST.test(archiveDigest) || hash(archive) !== archiveDigest)
+        fail('WORKSPACE_ARCHIVE_DIGEST_MISMATCH');
+    if (archive.length > MAX_ARCHIVE_BYTES)
+        fail('WORKSPACE_ARCHIVE_TOO_LARGE');
+    let data;
+    try {
+        data = archive[0] === 0x1f && archive[1] === 0x8b ? gunzipSync(archive, { maxOutputLength: MAX_SOURCE_BYTES }) : archive;
+    }
+    catch {
+        fail('WORKSPACE_ARCHIVE_INVALID');
+    }
+    if (data.length > MAX_SOURCE_BYTES || data.length % 512 !== 0)
+        fail('WORKSPACE_ARCHIVE_INVALID');
+    const files = [];
+    const seen = new Map();
+    let metadata = {};
+    let ended = false;
+    for (let offset = 0; offset < data.length;) {
+        const header = data.subarray(offset, offset + 512);
+        if (header.every(byte => byte === 0)) {
+            if (!data.subarray(offset).every(byte => byte === 0))
+                fail('WORKSPACE_ARCHIVE_TRAILING_DATA');
+            ended = true;
+            break;
+        }
+        let sum = 0;
+        for (let i = 0; i < 512; i++)
+            sum += i >= 148 && i < 156 ? 32 : header[i];
+        if (sum !== octal(header.subarray(148, 156)))
+            fail('WORKSPACE_ARCHIVE_CHECKSUM_INVALID');
+        const size = octal(header.subarray(124, 136));
+        const end = offset + 512 + size;
+        if (end > data.length)
+            fail('WORKSPACE_ARCHIVE_INVALID');
+        const body = data.subarray(offset + 512, end);
+        offset += 512 + Math.ceil(size / 512) * 512;
+        const type = String.fromCharCode(header[156]);
+        if (type === 'x' || type === 'g') {
+            const fields = pax(body);
+            if (type === 'g' && fields.path)
+                fail('WORKSPACE_ARCHIVE_INVALID');
+            if (type === 'x')
+                metadata = fields;
+            continue;
+        }
+        if (!['0', '\0', '5'].includes(type))
+            fail('WORKSPACE_ARCHIVE_LINK_OR_SPECIAL_FILE');
+        const prefix = tarText(header.subarray(345, 500));
+        let path = metadata.path ?? [prefix, tarText(header.subarray(0, 100))].filter(Boolean).join('/');
+        metadata = {};
+        if (type === '5')
+            path = path.replace(/\/$/, '');
+        sourcePath(path);
+        if (seen.has(path))
+            fail('WORKSPACE_ARCHIVE_DUPLICATE_PATH');
+        for (let parent = posix.dirname(path); parent !== '.'; parent = posix.dirname(parent)) {
+            if (seen.get(parent) === 'file')
+                fail('WORKSPACE_ARCHIVE_PATH_COLLISION');
+        }
+        if (type !== '5' && [...seen.keys()].some(other => other.startsWith(`${path}/`)))
+            fail('WORKSPACE_ARCHIVE_PATH_COLLISION');
+        seen.set(path, type === '5' ? 'directory' : 'file');
+        if (seen.size > MAX_SOURCE_FILES)
+            fail('WORKSPACE_ARCHIVE_TOO_MANY_FILES');
+        if (type === '5') {
+            if (size !== 0)
+                fail('WORKSPACE_ARCHIVE_INVALID');
+            continue;
+        }
+        files.push({ path, content: body, digest: hash(body), mode: octal(header.subarray(100, 108)) & 0o111 ? 0o755 : 0o644 });
+    }
+    if (!ended || Object.keys(metadata).length)
+        fail('WORKSPACE_ARCHIVE_INVALID');
+    sourceManifest(files);
+    return files;
+}
+/** A portable source checkpoint. Dependencies/build caches remain provider caches.
+ * Paths, modes and bytes (including binary assets) survive without a Git host. */
+// This function is embedded in the provider checkpoint program. Keep it closed
+// over built-ins only, with no nested named functions: keepNames bundling adds
+// an outer helper reference to those functions, which does not cross the wire.
+export function encodeTar(files) {
+    const chunks = [];
+    for (const file of [...files].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0)) {
+        const entries = [];
+        if (Buffer.byteLength(file.path) > 100) {
+            const record = `path=${file.path}\n`;
+            let length = Buffer.byteLength(record) + 2;
+            while (Buffer.byteLength(`${length} ${record}`) !== length)
+                length = Buffer.byteLength(`${length} ${record}`);
+            entries.push({ path: 'PaxHeader', content: Buffer.from(`${length} ${record}`), mode: 0o644, type: 'x' });
+        }
+        entries.push({ path: Buffer.byteLength(file.path) > 100 ? 'source' : file.path,
+            content: file.content, mode: file.mode, type: '0' });
+        for (const { path, content, mode, type } of entries) {
+            const header = Buffer.alloc(512);
+            header.write(path, 0, 100);
+            header.write(mode.toString(8).padStart(7, '0') + '\0', 100, 8);
+            header.write(content.length.toString(8).padStart(11, '0') + '\0', 124, 12);
+            header.fill(32, 148, 156);
+            header.write(type, 156, 1);
+            header.write('ustar\0', 257, 6);
+            header.write(header.reduce((a, b) => a + b, 0).toString(8).padStart(6, '0') + '\0 ', 148, 8);
+            chunks.push(header, content, Buffer.alloc((512 - content.length % 512) % 512));
+        }
+    }
+    return Buffer.concat([...chunks, Buffer.alloc(1024)]);
+}
+export function encodeSourceArchive(files) {
+    sourceManifest(files);
+    if (files.reduce((size, file) => size + file.content.length, 0) > MAX_SOURCE_BYTES)
+        throw Error('WORKSPACE_ARCHIVE_TOO_LARGE');
+    if (files.some(file => sourceDigest(file.content) !== file.digest))
+        throw Error('WORKSPACE_SOURCE_DIGEST_MISMATCH');
+    const archive = gzipSync(encodeTar(files));
+    validateWorkspaceArchive(archive, sourceDigest(archive));
+    return archive;
+}
+export function editSource(files, input) {
+    const previous = files.find(file => file.path === input.file);
+    if ((previous?.digest ?? null) !== input.expectedDigest)
+        throw Error('PROJECT_WORKSPACE_FILE_CHANGED');
+    const content = Buffer.from(input.text);
+    const replacement = { path: input.file, content, digest: sourceDigest(content), mode: previous?.mode ?? 0o644 };
+    return [...files.filter(file => file.path !== input.file), replacement];
+}

package/dist/manifest.d.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+export declare const digest: z.ZodString;
+export declare const gitCommit: z.ZodString;
+export declare const MAX_SOURCE_FILES = 20000;
+export declare const MAX_SOURCE_BYTES: number;
+export declare const MAX_ARCHIVE_BYTES: number;
+/** Shared by imports, archives, sandbox writes and restitutions. */
+export declare function sourcePath(value: string): string;
+export declare const sourceScope: z.ZodObject<{
+    appRoot: z.ZodString;
+    include: z.ZodArray<z.ZodString>;
+    exclude: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type SourceScope = z.infer<typeof sourceScope>;
+export declare const defaultSourceScope: SourceScope;
+export declare function inSourceScope(path: string, scope: SourceScope): boolean;
+export type SourceFile = {
+    path: string;
+    digest: string;
+    mode: number;
+};
+export declare function sourceManifest(files: SourceFile[]): SourceFile[];
+export declare const sourceIdentity: (files: SourceFile[]) => string;
+export declare function sourceChanges(before: SourceFile[], after: SourceFile[]): {
+    file: string;
+    change: "created" | "deleted" | "modified";
+    beforeDigest: string | null;
+    digest: string | null;
+    beforeMode: number | null;
+    mode: number | null;
+}[];
+export declare const sourceOrigin: z.ZodObject<{
+    commit: z.ZodString;
+}, z.core.$strict>;
+export declare const snapshotProof: z.ZodObject<{
+    revision: z.ZodString;
+    archiveDigest: z.ZodString;
+}, z.core.$strict>;
+export declare const sourceChange: z.ZodObject<{
+    format: z.ZodLiteral<1>;
+    projectShortId: z.ZodString;
+    workspaceId: z.ZodString;
+    releaseId: z.ZodString;
+    scope: z.ZodObject<{
+        appRoot: z.ZodString;
+        include: z.ZodArray<z.ZodString>;
+        exclude: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    origin: z.ZodOptional<z.ZodObject<{
+        commit: z.ZodString;
+    }, z.core.$strict>>;
+    base: z.ZodObject<{
+        revision: z.ZodString;
+        archiveDigest: z.ZodString;
+    }, z.core.$strict>;
+    result: z.ZodObject<{
+        revision: z.ZodString;
+        archiveDigest: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type SourceChange = z.infer<typeof sourceChange>;
+/** Object field order can change through storage and JSON transports. */
+export declare const sourceChangeIdentity: (change: SourceChange) => string;

package/dist/manifest.js

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+export const digest = z.string().regex(/^[a-f0-9]{64}$/);
+export const gitCommit = z.string().regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/);
+export const MAX_SOURCE_FILES = 20_000;
+export const MAX_SOURCE_BYTES = 256 * 1024 * 1024;
+export const MAX_ARCHIVE_BYTES = 64 * 1024 * 1024;
+/** Shared by imports, archives, sandbox writes and restitutions. */
+export function sourcePath(value) {
+    if (!value || value.length > 1024 || value.startsWith('/') || /[\\\x00-\x1f\x7f:]/.test(value))
+        throw Error('WORKSPACE_PATH_INVALID');
+    const parts = value.split('/');
+    if (parts.some(part => !part || part === '.' || part === '..' ||
+        (/[. ]$/.test(part) || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\.|$)/i.test(part)) ||
+        ['.git', '.ssh', '.aws', '.vercel', '.storystick', '.npmrc', '.netrc', '.pypirc', '.yarnrc.yml'].includes(part.toLowerCase()) ||
+        part.toLowerCase().startsWith('.env') || /^(id_rsa|id_ed25519|credentials)(\.|$)/i.test(part) || /\.(pem|key|p12|pfx)$/i.test(part)))
+        throw Error('WORKSPACE_PATH_FORBIDDEN');
+    return value;
+}
+const prefix = z.string().min(1).max(1024).refine(value => value === '.' ||
+    !value.startsWith('/') && !/[\\\x00-\x1f\x7f:*?]/.test(value) && value.split('/').every(p => p && p !== '.' && p !== '..'));
+export const sourceScope = z.object({
+    appRoot: prefix,
+    include: z.array(prefix).min(1).max(100),
+    exclude: z.array(prefix).max(100),
+}).strict();
+export const defaultSourceScope = { appRoot: '.', include: ['.'], exclude: [] };
+export function inSourceScope(path, scope) {
+    const contains = (p) => p === '.' || path === p || path.startsWith(p + '/');
+    return scope.include.some(contains) && !scope.exclude.some(contains);
+}
+export function sourceManifest(files) {
+    if (files.length > MAX_SOURCE_FILES)
+        throw Error('WORKSPACE_SOURCE_MANIFEST_INVALID');
+    const seen = new Set();
+    const manifest = files.map(({ path, digest: hash, mode }) => {
+        sourcePath(path);
+        // Reject ambiguous paths on case-insensitive/decomposing customer filesystems.
+        const key = path.normalize('NFC').toLowerCase();
+        if (seen.has(key) || !digest.safeParse(hash).success || ![0o644, 0o755].includes(mode))
+            throw Error('WORKSPACE_SOURCE_MANIFEST_INVALID');
+        seen.add(key);
+        return { path, digest: hash, mode };
+    }).sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    for (const key of seen) {
+        const parts = key.split('/');
+        for (let i = 1; i < parts.length; i++)
+            if (seen.has(parts.slice(0, i).join('/')))
+                throw Error('WORKSPACE_SOURCE_PATH_COLLISION');
+    }
+    return manifest;
+}
+export const sourceIdentity = (files) => JSON.stringify({ version: 1, files: sourceManifest(files) });
+export function sourceChanges(before, after) {
+    const a = new Map(before.map(f => [f.path, f])), b = new Map(after.map(f => [f.path, f]));
+    return [...new Set([...a.keys(), ...b.keys()])].sort().flatMap(file => {
+        const old = a.get(file), next = b.get(file);
+        return old?.digest === next?.digest && old?.mode === next?.mode ? [] : [{
+                file, change: !old ? 'created' : !next ? 'deleted' : 'modified',
+                beforeDigest: old?.digest ?? null, digest: next?.digest ?? null,
+                beforeMode: old?.mode ?? null, mode: next?.mode ?? null,
+            }];
+    });
+}
+export const sourceOrigin = z.object({ commit: gitCommit }).strict();
+export const snapshotProof = z.object({ revision: digest, archiveDigest: digest }).strict();
+export const sourceChange = z.object({
+    format: z.literal(1), projectShortId: z.string().regex(/^[a-z0-9]{8}$/),
+    workspaceId: z.string().min(1).max(120), releaseId: z.string().min(1).max(120),
+    scope: sourceScope, origin: sourceOrigin.optional(), base: snapshotProof, result: snapshotProof,
+}).strict();
+/** Object field order can change through storage and JSON transports. */
+export const sourceChangeIdentity = (change) => JSON.stringify(sourceChange.parse(change));

package/dist/recipe.d.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+/** Repository-relative commands shared by local preparation and remote execution.
+ * Validation describes commands; it never executes or grants permission to them. */
+export declare const executionPath: z.ZodString;
+export declare const executionDirectory: z.ZodUnion<readonly [z.ZodLiteral<".">, z.ZodString]>;
+export declare const workspaceRecipe: z.ZodObject<{
+    schemaCheck: z.ZodString;
+    schemaOutput: z.ZodOptional<z.ZodString>;
+    install: z.ZodArray<z.ZodObject<{
+        argv: z.ZodArray<z.ZodString>;
+        cwd: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<".">, z.ZodString]>>;
+    }, z.core.$strict>>;
+    checks: z.ZodArray<z.ZodObject<{
+        argv: z.ZodArray<z.ZodString>;
+        cwd: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<".">, z.ZodString]>>;
+        name: z.ZodString;
+    }, z.core.$strict>>;
+    preview: z.ZodObject<{
+        argv: z.ZodArray<z.ZodString>;
+        cwd: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<".">, z.ZodString]>>;
+        port: z.ZodNumber;
+        readyPath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    allowedHosts: z.ZodArray<z.ZodString>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+export declare const sourceConfiguration: z.ZodObject<{
+    scope: z.ZodObject<{
+        appRoot: z.ZodString;
+        include: z.ZodArray<z.ZodString>;
+        exclude: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    schemaVersion: z.ZodString;
+    recipe: z.ZodObject<{
+        schemaCheck: z.ZodString;
+        schemaOutput: z.ZodOptional<z.ZodString>;
+        install: z.ZodArray<z.ZodObject<{
+            argv: z.ZodArray<z.ZodString>;
+            cwd: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<".">, z.ZodString]>>;
+        }, z.core.$strict>>;
+        checks: z.ZodArray<z.ZodObject<{
+            argv: z.ZodArray<z.ZodString>;
+            cwd: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<".">, z.ZodString]>>;
+            name: z.ZodString;
+        }, z.core.$strict>>;
+        preview: z.ZodObject<{
+            argv: z.ZodArray<z.ZodString>;
+            cwd: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<".">, z.ZodString]>>;
+            port: z.ZodNumber;
+            readyPath: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        allowedHosts: z.ZodArray<z.ZodString>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type SourceConfiguration = z.infer<typeof sourceConfiguration>;
+/** Same conservative preset for a local checkout and an immutable remote tree.
+ * Only explicit repository facts enter; this function never reads or runs code. */
+export declare function nextSourceConfiguration(input: {
+    manifest: unknown;
+    files: string[];
+    schemaVersion: string;
+}): SourceConfiguration;

package/dist/recipe.js

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import { sourcePath, sourceScope } from './manifest.js';
+/** Repository-relative commands shared by local preparation and remote execution.
+ * Validation describes commands; it never executes or grants permission to them. */
+export const executionPath = z.string().refine((value) => {
+    try {
+        sourcePath(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}, 'Use a project-relative path; credentials and Git internals are excluded');
+// The project root is a command directory, never a source-file address.
+export const executionDirectory = z.union([z.literal('.'), executionPath]);
+const command = z
+    .object({
+    argv: z.array(z.string().min(1).max(2048)).min(1).max(32),
+    cwd: executionDirectory.optional(),
+})
+    .strict();
+export const workspaceRecipe = z
+    .object({
+    schemaCheck: z.string().min(1).max(80),
+    // Compiler-owned output, never a model-supplied schema or command.
+    schemaOutput: executionPath.optional(),
+    install: z.array(command).max(8),
+    checks: z
+        .array(command.extend({ name: z.string().min(1).max(80) }))
+        .min(1)
+        .max(8),
+    preview: command.extend({
+        port: z.number().int().min(1024).max(65535),
+        readyPath: z.string().startsWith('/').max(500).optional(),
+    }),
+    allowedHosts: z.array(z.string().regex(/^[a-z0-9][a-z0-9.-]*[a-z0-9]$/)).max(20),
+    env: z
+        .record(z.string().regex(/^(?:NEXT_PUBLIC_)?STORYSTICK_[A-Z0-9_]+$|^NODE_ENV$/), z.string().max(8192))
+        .optional(),
+})
+    .strict();
+export const sourceConfiguration = z
+    .object({
+    scope: sourceScope,
+    schemaVersion: z.string().min(1).max(128),
+    recipe: workspaceRecipe,
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const names = value.recipe.checks.map((check) => check.name);
+    if (!names.includes(value.recipe.schemaCheck))
+        ctx.addIssue({
+            code: 'custom',
+            path: ['recipe', 'schemaCheck'],
+            message: 'Must name one of the declared checks',
+        });
+    if (new Set(names).size !== names.length)
+        ctx.addIssue({
+            code: 'custom',
+            path: ['recipe', 'checks'],
+            message: 'Check names must be unique',
+        });
+    if (!value.recipe.schemaOutput)
+        ctx.addIssue({
+            code: 'custom',
+            path: ['recipe', 'schemaOutput'],
+            message: 'Declare the compiler output used to verify release grammar',
+        });
+});
+/** Same conservative preset for a local checkout and an immutable remote tree.
+ * Only explicit repository facts enter; this function never reads or runs code. */
+export function nextSourceConfiguration(input) {
+    const pkg = z.object({
+        workspaces: z.unknown().optional(),
+        dependencies: z.record(z.string(), z.string()).optional(),
+        devDependencies: z.record(z.string(), z.string()).optional(),
+        scripts: z.record(z.string(), z.string()).optional(),
+    }).parse(input.manifest);
+    if (pkg.workspaces !== undefined || input.files.includes('pnpm-workspace.yaml'))
+        throw Error('A monorepo needs an explicit source scope and command directories. Use a reviewed source configuration.');
+    if (!(pkg.dependencies?.next || pkg.devDependencies?.next) || !pkg.scripts?.dev || !pkg.scripts?.build)
+        throw Error('The Next.js preset needs next and the dev/build scripts. Use a reviewed source configuration for a different setup.');
+    if (!(pkg.devDependencies?.['@storystick/cli'] || pkg.dependencies?.['@storystick/cli']))
+        throw Error('Install @storystick/cli in this project before using the preset.');
+    const locks = ['pnpm-lock.yaml', 'package-lock.json'].filter(file => input.files.includes(file));
+    if (locks.length !== 1)
+        throw Error('The preset needs exactly one pnpm-lock.yaml or package-lock.json. Use a reviewed source configuration for a different package manager.');
+    const pnpm = locks[0] === 'pnpm-lock.yaml';
+    const run = (name) => [pnpm ? 'pnpm' : 'npm', 'run', name];
+    const cli = pnpm ? ['pnpm', 'exec', 'storystick'] : ['npx', '--no-install', 'storystick'];
+    const output = 'generated/storystick-schema.json';
+    return sourceConfiguration.parse({
+        scope: { appRoot: '.', include: ['.'], exclude: ['.storystick', '.vercel', '.next', 'node_modules', 'generated'] },
+        schemaVersion: input.schemaVersion,
+        recipe: {
+            install: [{ argv: pnpm ? ['pnpm', 'install', '--frozen-lockfile'] : ['npm', 'ci'] }, { argv: [...cli, 'generate'] }],
+            checks: [{ name: 'schema', argv: [...cli, 'schema', '--out', output] }, { name: 'build', argv: run('build') }],
+            schemaCheck: 'schema', schemaOutput: output,
+            preview: { argv: [...run('dev'), ...(pnpm ? [] : ['--']), '--hostname', '0.0.0.0', '--port', '3000'], port: 3000 },
+            allowedHosts: [],
+        },
+    });
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@storystick/source",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-rc.1",
+  "type": "module",
+  "license": "FSL-1.1-MIT",
+  "files": [
+    "dist",
+    "PUBLIC-API.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": false,
+    "tag": "beta"
+  },
+  "exports": {
+    "./manifest": {
+      "types": "./dist/manifest.d.ts",
+      "import": "./dist/manifest.js"
+    },
+    "./archive": {
+      "types": "./dist/archive.d.ts",
+      "import": "./dist/archive.js"
+    },
+    "./recipe": {
+      "types": "./dist/recipe.d.ts",
+      "import": "./dist/recipe.js"
+    }
+  },
+  "dependencies": {
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "typescript": "^5.8.2",
+    "vitest": "^3.1.1"
+  },
+  "engines": {
+    "node": ">=24.19.0 <25"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/withstorystick/storystick.git",
+    "directory": "packages/source"
+  },
+  "homepage": "https://storystick.app",
+  "bugs": {
+    "url": "https://storystick.app"
+  },
+  "scripts": {
+    "build": "node ../../scripts/package-dist.mjs clean && tsc",
+    "test": "vitest run"
+  }
 }