@shipstatic/types 2.23.0 → 2.24.0-beta.2

package/dist/index.d.ts

@@ -848,9 +848,58 @@ export declare const DEPLOY_FIELDS: {
     readonly PRERENDER: "prerender";
     /** @internal Server-processing flag — first-party `/upload` only. */
     readonly SPA: "spa";
+    /**
+     * @internal The build settings, first-party `/upload` only and meaningful
+     * only with `BUILD`: the command to run instead of the manifest's build
+     * script, and the folder the site lands in. See {@link BUILD_SETTINGS}.
+     */
+    readonly BUILD_COMMAND: "buildCommand";
+    /** @internal See {@link DEPLOY_FIELDS.BUILD_COMMAND}. */
+    readonly OUTPUT_DIR: "outputDir";
     /** @internal reCAPTCHA proof — `web/www`'s public uploader only. */
     readonly CAPTCHA: "captcha";
 };
+/**
+ * The JSON deploy body's file grammar: the OTHER body `POST /upload` accepts,
+ * beside the multipart one {@link DEPLOY_FIELDS} names. A JSON caller sends
+ * `{ files: [{ path, content, encoding? }] }`, and this is the whole of what
+ * one entry may say: three field names, two encodings, one default.
+ *
+ * Declared once because the grammar has three independent holders that the
+ * wire forces to restate it: the API's zod schema (the original), the hosted
+ * MCP's tool input, and the n8n community node, which cannot import this
+ * under n8n Cloud's zero-dependency rule and fences its copy against this
+ * object instead. Each had its own literal table until 2.24.0; the last two
+ * types convoys walked without minting the owner, which is exactly the drift
+ * the No-Fourth-Category Law's deferral clause names.
+ *
+ * `content` is the file's bytes as text: raw for `utf-8` (the default, and
+ * the right choice for HTML, CSS, JS, JSON and SVG), base64 for binary.
+ */
+export declare const DEPLOY_FILE_GRAMMAR: {
+    /** Relative path within the site, no leading slash. */
+    readonly PATH: "path";
+    /** The file's bytes, as text in the entry's encoding. */
+    readonly CONTENT: "content";
+    /** Optional; one of {@link DEPLOY_FILE_GRAMMAR.ENCODINGS}. */
+    readonly ENCODING: "encoding";
+    /** What an entry that names no encoding means. */
+    readonly DEFAULT_ENCODING: "utf-8";
+    /** The closed set. `utf-8` is raw text; `base64` is for binary only. */
+    readonly ENCODINGS: readonly ["utf-8", "base64"];
+};
+/** One of the two encodings a JSON deploy entry may name. */
+export type DeployFileEncoding = (typeof DEPLOY_FILE_GRAMMAR.ENCODINGS)[number];
+/**
+ * One file entry of a JSON deploy, in the grammar above. The wire shape the
+ * API parses and the hosted MCP's tool input decodes; `encoding` absent means
+ * {@link DEPLOY_FILE_GRAMMAR.DEFAULT_ENCODING}.
+ */
+export interface DeployFileSpec {
+    path: string;
+    content: string;
+    encoding?: DeployFileEncoding;
+}
 /**
  * All possible error types in the ShipStatic platform.
  *
@@ -1806,6 +1855,20 @@ export interface DeploymentUploadOptions {
     prerender?: boolean;
     /** @internal Trigger server-side SPA detection. Only available via /upload endpoint. */
     spa?: boolean;
+    /**
+     * @internal The command the build runs instead of the manifest's own
+     * `build` script (`npm run build:site`, `hugo`, …). Only with `build`, only
+     * via /upload; format in {@link BUILD_SETTINGS}, checked by
+     * {@link validateBuildCommand}.
+     */
+    buildCommand?: string;
+    /**
+     * @internal The folder the built site lands in (`public`, `dist/site`),
+     * relative to the project root, for projects whose output the builder does
+     * not find on its own. Only with `build`, only via /upload; format in
+     * {@link BUILD_SETTINGS}, checked by {@link validateOutputDir}.
+     */
+    outputDir?: string;
     /** @internal reCAPTCHA proof for the anonymous human deploy channel. Only available via /upload endpoint. */
     captcha?: string;
     /**
@@ -2297,6 +2360,41 @@ export declare function serializeLabels(labels: string[] | undefined): string |
  * @example deserializeLabels('') → []
  */
 export declare function deserializeLabels(labelsJson: string | null): string[];
+/**
+ * The format of the two per-deploy build settings a caller may name when the
+ * builder's own detection is not enough: the command to run and the folder
+ * the site lands in. Format rules only, the format/policy split this file
+ * keeps everywhere: WHAT a value may look like lives here so both the console
+ * (fast feedback) and the API (the boundary) refuse the same strings; whether
+ * the command builds anything is the build's verdict, not a rule.
+ *
+ * Both are read only by first-party `/upload`, only with `build`, and both
+ * run inside the throwaway container that already runs the project's own
+ * arbitrary code, which is why the command's format is a shape rule (one
+ * line, bounded) and not a safety rule. The folder's rule is what keeps it a
+ * folder OF the project: relative, no parent segments, no leading slash.
+ */
+export declare const BUILD_SETTINGS: {
+    /** A build command is one line, non-empty, and bounded. */
+    readonly COMMAND_MAX_LENGTH: 200;
+    /** An output folder is a bounded relative path. */
+    readonly OUTPUT_DIR_MAX_LENGTH: 100;
+    /** Path segments and separators only: `dist`, `dist/site`, `.output/public`. */
+    readonly OUTPUT_DIR_PATTERN: RegExp;
+};
+/**
+ * Validate an optional build command and return it normalized (trimmed).
+ * Absent → `undefined`. Present → one line, 1 to
+ * {@link BUILD_SETTINGS.COMMAND_MAX_LENGTH} characters, no control characters.
+ */
+export declare function validateBuildCommand(value: unknown): string | undefined;
+/**
+ * Validate an optional output folder and return it normalized (trimmed, no
+ * trailing slash). Absent → `undefined`. Present → a relative path of plain
+ * segments, no `..`, no leading slash, at most
+ * {@link BUILD_SETTINGS.OUTPUT_DIR_MAX_LENGTH} characters.
+ */
+export declare function validateOutputDir(value: unknown): string | undefined;
 /**
  * Length constraints for the optional deployment password
  * (`DeploymentUploadOptions.password`). Single source of truth shared across

package/dist/index.js

@@ -310,9 +310,46 @@ export const DEPLOY_FIELDS = {
     PRERENDER: 'prerender',
     /** @internal Server-processing flag — first-party `/upload` only. */
     SPA: 'spa',
+    /**
+     * @internal The build settings, first-party `/upload` only and meaningful
+     * only with `BUILD`: the command to run instead of the manifest's build
+     * script, and the folder the site lands in. See {@link BUILD_SETTINGS}.
+     */
+    BUILD_COMMAND: 'buildCommand',
+    /** @internal See {@link DEPLOY_FIELDS.BUILD_COMMAND}. */
+    OUTPUT_DIR: 'outputDir',
     /** @internal reCAPTCHA proof — `web/www`'s public uploader only. */
     CAPTCHA: 'captcha',
 };
+/**
+ * The JSON deploy body's file grammar: the OTHER body `POST /upload` accepts,
+ * beside the multipart one {@link DEPLOY_FIELDS} names. A JSON caller sends
+ * `{ files: [{ path, content, encoding? }] }`, and this is the whole of what
+ * one entry may say: three field names, two encodings, one default.
+ *
+ * Declared once because the grammar has three independent holders that the
+ * wire forces to restate it: the API's zod schema (the original), the hosted
+ * MCP's tool input, and the n8n community node, which cannot import this
+ * under n8n Cloud's zero-dependency rule and fences its copy against this
+ * object instead. Each had its own literal table until 2.24.0; the last two
+ * types convoys walked without minting the owner, which is exactly the drift
+ * the No-Fourth-Category Law's deferral clause names.
+ *
+ * `content` is the file's bytes as text: raw for `utf-8` (the default, and
+ * the right choice for HTML, CSS, JS, JSON and SVG), base64 for binary.
+ */
+export const DEPLOY_FILE_GRAMMAR = {
+    /** Relative path within the site, no leading slash. */
+    PATH: 'path',
+    /** The file's bytes, as text in the entry's encoding. */
+    CONTENT: 'content',
+    /** Optional; one of {@link DEPLOY_FILE_GRAMMAR.ENCODINGS}. */
+    ENCODING: 'encoding',
+    /** What an entry that names no encoding means. */
+    DEFAULT_ENCODING: 'utf-8',
+    /** The closed set. `utf-8` is raw text; `base64` is for binary only. */
+    ENCODINGS: ['utf-8', 'base64'],
+};
 // =============================================================================
 // ERROR SYSTEM
 // =============================================================================
@@ -1812,6 +1849,74 @@ export function deserializeLabels(labelsJson) {
     }
 }
 // =============================================================================
+// BUILD SETTINGS
+// =============================================================================
+/**
+ * The format of the two per-deploy build settings a caller may name when the
+ * builder's own detection is not enough: the command to run and the folder
+ * the site lands in. Format rules only, the format/policy split this file
+ * keeps everywhere: WHAT a value may look like lives here so both the console
+ * (fast feedback) and the API (the boundary) refuse the same strings; whether
+ * the command builds anything is the build's verdict, not a rule.
+ *
+ * Both are read only by first-party `/upload`, only with `build`, and both
+ * run inside the throwaway container that already runs the project's own
+ * arbitrary code, which is why the command's format is a shape rule (one
+ * line, bounded) and not a safety rule. The folder's rule is what keeps it a
+ * folder OF the project: relative, no parent segments, no leading slash.
+ */
+export const BUILD_SETTINGS = {
+    /** A build command is one line, non-empty, and bounded. */
+    COMMAND_MAX_LENGTH: 200,
+    /** An output folder is a bounded relative path. */
+    OUTPUT_DIR_MAX_LENGTH: 100,
+    /** Path segments and separators only: `dist`, `dist/site`, `.output/public`. */
+    OUTPUT_DIR_PATTERN: /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/,
+};
+/**
+ * Validate an optional build command and return it normalized (trimmed).
+ * Absent → `undefined`. Present → one line, 1 to
+ * {@link BUILD_SETTINGS.COMMAND_MAX_LENGTH} characters, no control characters.
+ */
+export function validateBuildCommand(value) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    if (typeof value !== 'string') {
+        throw ShipError.validation('Build command must be a string');
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0 || trimmed.length > BUILD_SETTINGS.COMMAND_MAX_LENGTH) {
+        throw ShipError.validation(`Build command must be between 1 and ${BUILD_SETTINGS.COMMAND_MAX_LENGTH} characters`);
+    }
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: a command is one line; a newline or any other control character is a second one
+    if (/[\x00-\x1f\x7f]/.test(trimmed)) {
+        throw ShipError.validation('Build command must be a single line');
+    }
+    return trimmed;
+}
+/**
+ * Validate an optional output folder and return it normalized (trimmed, no
+ * trailing slash). Absent → `undefined`. Present → a relative path of plain
+ * segments, no `..`, no leading slash, at most
+ * {@link BUILD_SETTINGS.OUTPUT_DIR_MAX_LENGTH} characters.
+ */
+export function validateOutputDir(value) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    if (typeof value !== 'string') {
+        throw ShipError.validation('Output folder must be a string');
+    }
+    const trimmed = value.trim().replace(/\/+$/, '');
+    if (trimmed.length === 0 || trimmed.length > BUILD_SETTINGS.OUTPUT_DIR_MAX_LENGTH) {
+        throw ShipError.validation(`Output folder must be between 1 and ${BUILD_SETTINGS.OUTPUT_DIR_MAX_LENGTH} characters`);
+    }
+    if (!BUILD_SETTINGS.OUTPUT_DIR_PATTERN.test(trimmed) ||
+        trimmed.split('/').some((segment) => segment === '..' || segment === '.')) {
+        throw ShipError.validation('Output folder must be a relative path inside the project, like dist or dist/site');
+    }
+    return trimmed;
+}
+// =============================================================================
 // PASSWORD UTILITIES
 // =============================================================================
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/types",
-  "version": "2.23.0",
+  "version": "2.24.0-beta.2",
   "description": "Shared TypeScript types for the ShipStatic platform.",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -932,10 +932,62 @@ export const DEPLOY_FIELDS = {
   PRERENDER: 'prerender',
   /** @internal Server-processing flag — first-party `/upload` only. */
   SPA: 'spa',
+  /**
+   * @internal The build settings, first-party `/upload` only and meaningful
+   * only with `BUILD`: the command to run instead of the manifest's build
+   * script, and the folder the site lands in. See {@link BUILD_SETTINGS}.
+   */
+  BUILD_COMMAND: 'buildCommand',
+  /** @internal See {@link DEPLOY_FIELDS.BUILD_COMMAND}. */
+  OUTPUT_DIR: 'outputDir',
   /** @internal reCAPTCHA proof — `web/www`'s public uploader only. */
   CAPTCHA: 'captcha',
 } as const;
 
+/**
+ * The JSON deploy body's file grammar: the OTHER body `POST /upload` accepts,
+ * beside the multipart one {@link DEPLOY_FIELDS} names. A JSON caller sends
+ * `{ files: [{ path, content, encoding? }] }`, and this is the whole of what
+ * one entry may say: three field names, two encodings, one default.
+ *
+ * Declared once because the grammar has three independent holders that the
+ * wire forces to restate it: the API's zod schema (the original), the hosted
+ * MCP's tool input, and the n8n community node, which cannot import this
+ * under n8n Cloud's zero-dependency rule and fences its copy against this
+ * object instead. Each had its own literal table until 2.24.0; the last two
+ * types convoys walked without minting the owner, which is exactly the drift
+ * the No-Fourth-Category Law's deferral clause names.
+ *
+ * `content` is the file's bytes as text: raw for `utf-8` (the default, and
+ * the right choice for HTML, CSS, JS, JSON and SVG), base64 for binary.
+ */
+export const DEPLOY_FILE_GRAMMAR = {
+  /** Relative path within the site, no leading slash. */
+  PATH: 'path',
+  /** The file's bytes, as text in the entry's encoding. */
+  CONTENT: 'content',
+  /** Optional; one of {@link DEPLOY_FILE_GRAMMAR.ENCODINGS}. */
+  ENCODING: 'encoding',
+  /** What an entry that names no encoding means. */
+  DEFAULT_ENCODING: 'utf-8',
+  /** The closed set. `utf-8` is raw text; `base64` is for binary only. */
+  ENCODINGS: ['utf-8', 'base64'],
+} as const;
+
+/** One of the two encodings a JSON deploy entry may name. */
+export type DeployFileEncoding = (typeof DEPLOY_FILE_GRAMMAR.ENCODINGS)[number];
+
+/**
+ * One file entry of a JSON deploy, in the grammar above. The wire shape the
+ * API parses and the hosted MCP's tool input decodes; `encoding` absent means
+ * {@link DEPLOY_FILE_GRAMMAR.DEFAULT_ENCODING}.
+ */
+export interface DeployFileSpec {
+  path: string;
+  content: string;
+  encoding?: DeployFileEncoding;
+}
+
 // =============================================================================
 // ERROR SYSTEM
 // =============================================================================
@@ -2661,6 +2713,20 @@ export interface DeploymentUploadOptions {
   prerender?: boolean;
   /** @internal Trigger server-side SPA detection. Only available via /upload endpoint. */
   spa?: boolean;
+  /**
+   * @internal The command the build runs instead of the manifest's own
+   * `build` script (`npm run build:site`, `hugo`, …). Only with `build`, only
+   * via /upload; format in {@link BUILD_SETTINGS}, checked by
+   * {@link validateBuildCommand}.
+   */
+  buildCommand?: string;
+  /**
+   * @internal The folder the built site lands in (`public`, `dist/site`),
+   * relative to the project root, for projects whose output the builder does
+   * not find on its own. Only with `build`, only via /upload; format in
+   * {@link BUILD_SETTINGS}, checked by {@link validateOutputDir}.
+   */
+  outputDir?: string;
   /** @internal reCAPTCHA proof for the anonymous human deploy channel. Only available via /upload endpoint. */
   captcha?: string;
   /**
@@ -3300,6 +3366,84 @@ export function deserializeLabels(labelsJson: string | null): string[] {
   }
 }
 
+// =============================================================================
+// BUILD SETTINGS
+// =============================================================================
+
+/**
+ * The format of the two per-deploy build settings a caller may name when the
+ * builder's own detection is not enough: the command to run and the folder
+ * the site lands in. Format rules only, the format/policy split this file
+ * keeps everywhere: WHAT a value may look like lives here so both the console
+ * (fast feedback) and the API (the boundary) refuse the same strings; whether
+ * the command builds anything is the build's verdict, not a rule.
+ *
+ * Both are read only by first-party `/upload`, only with `build`, and both
+ * run inside the throwaway container that already runs the project's own
+ * arbitrary code, which is why the command's format is a shape rule (one
+ * line, bounded) and not a safety rule. The folder's rule is what keeps it a
+ * folder OF the project: relative, no parent segments, no leading slash.
+ */
+export const BUILD_SETTINGS = {
+  /** A build command is one line, non-empty, and bounded. */
+  COMMAND_MAX_LENGTH: 200,
+  /** An output folder is a bounded relative path. */
+  OUTPUT_DIR_MAX_LENGTH: 100,
+  /** Path segments and separators only: `dist`, `dist/site`, `.output/public`. */
+  OUTPUT_DIR_PATTERN: /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/,
+} as const;
+
+/**
+ * Validate an optional build command and return it normalized (trimmed).
+ * Absent → `undefined`. Present → one line, 1 to
+ * {@link BUILD_SETTINGS.COMMAND_MAX_LENGTH} characters, no control characters.
+ */
+export function validateBuildCommand(value: unknown): string | undefined {
+  if (value === undefined || value === null || value === '') return undefined;
+  if (typeof value !== 'string') {
+    throw ShipError.validation('Build command must be a string');
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0 || trimmed.length > BUILD_SETTINGS.COMMAND_MAX_LENGTH) {
+    throw ShipError.validation(
+      `Build command must be between 1 and ${BUILD_SETTINGS.COMMAND_MAX_LENGTH} characters`,
+    );
+  }
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: a command is one line; a newline or any other control character is a second one
+  if (/[\x00-\x1f\x7f]/.test(trimmed)) {
+    throw ShipError.validation('Build command must be a single line');
+  }
+  return trimmed;
+}
+
+/**
+ * Validate an optional output folder and return it normalized (trimmed, no
+ * trailing slash). Absent → `undefined`. Present → a relative path of plain
+ * segments, no `..`, no leading slash, at most
+ * {@link BUILD_SETTINGS.OUTPUT_DIR_MAX_LENGTH} characters.
+ */
+export function validateOutputDir(value: unknown): string | undefined {
+  if (value === undefined || value === null || value === '') return undefined;
+  if (typeof value !== 'string') {
+    throw ShipError.validation('Output folder must be a string');
+  }
+  const trimmed = value.trim().replace(/\/+$/, '');
+  if (trimmed.length === 0 || trimmed.length > BUILD_SETTINGS.OUTPUT_DIR_MAX_LENGTH) {
+    throw ShipError.validation(
+      `Output folder must be between 1 and ${BUILD_SETTINGS.OUTPUT_DIR_MAX_LENGTH} characters`,
+    );
+  }
+  if (
+    !BUILD_SETTINGS.OUTPUT_DIR_PATTERN.test(trimmed) ||
+    trimmed.split('/').some((segment) => segment === '..' || segment === '.')
+  ) {
+    throw ShipError.validation(
+      'Output folder must be a relative path inside the project, like dist or dist/site',
+    );
+  }
+  return trimmed;
+}
+
 // =============================================================================
 // PASSWORD UTILITIES
 // =============================================================================