dataiku-sdk 1.1.0 → 3.0.0

package/LICENSE

@@ -1,21 +1,111 @@
-MIT License
+Dataiku SDK Limited Use License
+Version 1.0 — 31 August 2026
 
 Copyright (c) 2026 clssck
 
-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
+By copying, installing, accessing, or using this software and its associated
+documentation (the "Software"), you agree to this license.
+
+1. Definitions
+
+"Licensor" means clssck, the copyright holder.
+
+"Individual" means a natural person acting solely on their own behalf. A person
+acting for an employer, client, company, or other organization is not acting as
+an Individual for that use.
+
+"Company" means a for-profit legal entity, including a sole proprietorship,
+partnership, corporation, or limited liability company. Companies under common
+control are treated as one Company.
+
+"Annual Revenue" means a Company's total gross revenue, together with the gross
+revenue of every entity under common control, for its most recently completed
+fiscal year, before deductions. A Company without a completed fiscal year must
+use its good-faith projected gross revenue for its first twelve months. Revenue
+in another currency must be converted to United States dollars using a
+reasonable, consistently applied exchange rate.
+
+"Qualified User" means either:
+
+(a) an Individual; or
+(b) a Company with Annual Revenue of less than US $1,000,000.
+
+2. Free Limited License for Qualified Users
+
+Subject to every term of this license, the Licensor grants each Qualified User
+a non-exclusive, non-transferable, and non-sublicensable license, without
+a license fee, to copy, install, and run unmodified copies of the Software for
+the Qualified User's own use.
+
+Use by an employee, contractor, agent, or other person on behalf of a Company is
+use by that Company. An Individual license does not extend to such use.
+
+3. Users That Do Not Qualify
+
+A Company with Annual Revenue of US $1,000,000 or more, and any person or entity
+that is not a Qualified User, receives no right to use the Software under
+Section 2. Such a user must request and obtain a separate written license from
+the Licensor before copying, installing, or using the Software. Public access
+to the source code does not itself grant permission to use it.
+
+License and approval requests may be submitted to the Licensor through:
+https://github.com/clssck/dataiku-sdk
+
+4. Prior Written Approval Required
+
+The rights granted in Section 2 do not include any right to:
+
+(a) modify, adapt, translate, or create derivative works of the Software,
+including modifications made only for private or internal use; or
+(b) publish, distribute, provide, transfer, sublicense, sell, or otherwise make
+all or any part of the Software available to another person or entity, whether
+in source, binary, modified, or unmodified form.
+
+Each activity listed above requires the Licensor's prior written approval.
+Approval of one activity or version does not approve another. The Licensor may
+condition or deny approval at its discretion.
+
+5. Attribution and Citation
+
+Every permitted use must preserve all copyright, attribution, and license
+notices included with the Software. The following credit and link must also
+appear in documentation, notices, or an About page accompanying the use:
+
+    dataiku-sdk by clssck — https://github.com/clssck/dataiku-sdk
+
+The credit must be reasonably prominent and may not suggest endorsement by the
+Licensor. Prior written approval under Section 4 does not waive these
+requirements unless the approval expressly says so.
+
+6. No Other Rights
+
+The Software is licensed, not sold. Except for the limited rights expressly
+granted in this license or in a separate written agreement signed by the
+Licensor, the Licensor reserves all rights. This license grants no right to use
+any trademark, service mark, trade name, or logo of the Licensor.
+
+7. Termination
+
+This license terminates automatically upon breach. After termination, you must
+stop using the Software and delete every copy in your possession or control.
+Sections 5, 6, 8, 9, and 10 survive termination.
+
+8. Disclaimer of Warranty
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE, TITLE, AND NON-INFRINGEMENT. YOU BEAR ALL RISK ARISING FROM USE OF THE
 SOFTWARE.
+
+9. Limitation of Liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE LICENSOR WILL NOT BE LIABLE FOR ANY
+CLAIM, LOSS, OR DAMAGES ARISING FROM OR RELATED TO THE SOFTWARE OR THIS LICENSE,
+WHETHER IN CONTRACT, TORT, OR OTHERWISE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+10. Earlier Licenses
+
+This license applies only to copies of the Software distributed with this
+license. It does not revoke or restrict rights validly granted for copies that a
+recipient previously received under another license.

package/README.md

@@ -4,7 +4,7 @@ Agent-only TypeScript SDK and `dss` CLI for Dataiku DSS automation.
 
 ## Platform support
 
-The published `dss` CLI supports Linux, macOS, and Windows under Bun >= 1.3.14 or Node.js >= 22.15.0. The release gate runs Bun 1.3.14 with Node 24 on all three operating systems, plus a lightweight minimum-Node 22.15 package smoke on Linux. The runtime dependency is pure JavaScript, so the same package also runs on runtime-supported x64 and ARM64 systems.
+The published `dss` CLI requires Bun >= 1.4.0 and supports Linux, macOS, and Windows. The release gate runs Bun 1.4.0 on all three operating systems. The runtime dependency is pure JavaScript, so the same package also runs on every Bun-supported x64 and ARM64 system.
 
 Run directly with Bun:
 
@@ -17,10 +17,11 @@ Or install the npm binary:
 ```text
 npm install --global dataiku-sdk
 ```
+The installed `dss` bin bootstraps Bun with automatic `.env` preloading disabled, so Bun >= 1.4.0 must be on `PATH`; the CLI's own `.env` handling stays authoritative. `bunx --bun` forces Bun's Node-compatibility mode, which provides the same no-preload guarantee across operating systems.
 
-Bun is the primary development runtime and package manager. Examples below assume an installed `dss` binary. From a checkout, use `bun --no-env-file src/cli.ts ...` or the cross-runtime `bun --no-env-file ./bin/dss.js ...` launcher. Node users can invoke the same launcher as `node ./bin/dss.js ...`; if `dist/` is absent, it delegates to Bun. From another working directory, pass the checkout's absolute `bin/dss.js` path to Bun or Node.
+Bun is the only supported runtime and the package manager. Examples below assume an installed `dss` binary. From a checkout, use `bun --no-env-file src/cli.ts ...` or the packaged launcher `bun --no-env-file ./bin/dss.js ...`. From another working directory, pass the checkout's absolute `bin/dss.js` path to Bun.
 `--no-env-file` disables Bun's automatic preloading only; the CLI still applies its documented `.env` handling unless `DATAIKU_DISABLE_ENV=1` is set.
-`dss version` reports whether the running code came from `source` or `dist`, the Node/Bun runtime, the packaged build revision when available, and `staleBuild` when that revision differs from the checkout. Release builds generate `dist/build-metadata.json`; source snapshots without Git metadata still build but report no build revision.
+`dss version` reports whether the running code came from `source` or `dist`, the runtime (always `bun`), the packaged build revision when available, and `staleBuild` when that revision differs from the checkout. Release builds generate `dist/build-metadata.json`; source snapshots without Git metadata still build but report no build revision.
 
 ## CLI contract
 
@@ -135,7 +136,8 @@ dss app validate-manifest --project-key MYAPP_INSTANCE
 dss app compare-manifest my-app --project-key MYAPP_INSTANCE
 dss app create-instance my-app --data '{"targetProjectKey":"MYAPP_INSTANCE"}' --wait --record-cleanup cleanup.jsonl
 dss app manifest-version --project-key MYAPP_TEMPLATE
-dss app set-manifest-version --manifest-version 1.4.0 --project-key MYAPP_TEMPLATE
+dss app successor-preflight my-app --from MYAPP_INSTANCE --to MYAPP_INSTANCE_V2 --copy-permissions
+dss app set-manifest-version --manifest-version 1.4.0 --expect-hash PREFLIGHT_TEMPLATE_MANIFEST_HASH --project-key MYAPP_TEMPLATE
 dss app create-successor-instance my-app --from MYAPP_INSTANCE --to MYAPP_INSTANCE_V2 --copy-permissions --record-cleanup cleanup.jsonl
 dss app verify-instance my-app --project-key MYAPP_INSTANCE_V2 --expect-version 1.4.0
 dss app permissions-snapshot --project-key MYAPP_INSTANCE --output permissions.json
@@ -182,6 +184,12 @@ dss app compare-manifest APP_ID --project-key RELEASE_INSTANCE
 # Read the raw `version` from the public app manifest (string fields only; never appVersion).
 dss app manifest-version --project-key APP_TEMPLATE
 
+# Run every read-only successor gate before changing the template version. This validates the
+# template references, verifies the predecessor, proves target absence, and optionally snapshots
+# the predecessor ACL. Keep template.manifestHash from the result for the next command.
+dss app successor-preflight APP_ID \
+  --from RELEASE_INSTANCE --to RELEASE_INSTANCE_V2 --copy-permissions
+
 # Write version/versionNotes through the public app-manifest endpoint. This is NOT a publish
 # transaction: it only changes the raw manifest metadata. --expect-hash SHA256 is a non-atomic
 # stale-read guard, not a conditional write: it refuses the write when the manifest already
@@ -189,7 +197,8 @@ dss app manifest-version --project-key APP_TEMPLATE
 # overwrite a write landing between its read and PUT, and the final read cannot detect that lost
 # update when this command's payload wins. Every result reports
 # concurrencyControl: "client-side-non-atomic-stale-read-check".
-dss app set-manifest-version --manifest-version 1.4.0 --project-key APP_TEMPLATE
+dss app set-manifest-version --manifest-version 1.4.0 \
+  --expect-hash PREFLIGHT_TEMPLATE_MANIFEST_HASH --project-key APP_TEMPLATE
 
 # Create an instance only after its target key is confirmed absent, wait on the DSS future, and
 # record deterministic cleanup.
@@ -200,7 +209,8 @@ dss app create-instance APP_ID \
 # Roll out a new template version to an existing instance as an additive successor: the old
 # instance is never modified or deleted, and the command always waits on the DSS future
 # (there is no --wait flag). The recorded cleanup entry targets only the new project key. If DSS
-# accepts creation but returns no future ID, cleanup stops unresolved instead of racing creation.
+# may have accepted creation but no future ID is returned, the outcome is indeterminate and no
+# unbound cleanup entry is written.
 dss app create-successor-instance APP_ID \
   --from RELEASE_INSTANCE --to RELEASE_INSTANCE_V2 \
   --name "Release instance v2" --copy-permissions --record-cleanup cleanup.jsonl
@@ -233,12 +243,24 @@ managed-folder IDs, and runtime-form parameter names against supported public pr
 
 Some DSS deployments hide unknown project keys behind `403` instead of returning `404`.
 Instance creation requires confirmed target absence before POST: an inaccessible target not present
-in the visible project list is still unconfirmed and is rejected rather than risking cleanup
-against a pre-existing project. A definitive create rejection never produces a cleanup entry.
+in the visible project and app-instance lists is still unconfirmed and is rejected with
+`target_absence_unverifiable` / `permission_or_environment` rather than risking cleanup against a
+pre-existing project. Choosing another key does not solve deployments that mask every unknown key.
+DSS exposes no permission-independent public availability endpoint, and its published app-instance
+API does not guarantee duplicate-key rejection before any write or non-overwrite behavior, so
+there is no unsafe force or unconfirmed-target bypass. Use an identity with global project
+visibility. A definitive create rejection never produces a cleanup entry; an ambiguous POST
+without a future ID or verified
+incarnation also produces no cleanup entry.
+
+Static create plans describe, but do not execute, these reads:
+`preflightExecuted:false` and `preflightWillRunDuringApply:true`. Run `successor-preflight` when
+live read evidence is required before changing the template version.
 
 Every new cleanup entry records the canonical DSS URL. App-instance cleanup records a
-`creationTag` hash observed after the DSS future identifies the target key; unconfirmed creation
-stops unresolved. The future target and later `creationTag` are independent, non-atomic
+`creationTag` hash observed after the DSS future identifies the target key; a future-addressable
+entry stops unresolved until the future names that key and its incarnation can be bound. An
+ambiguous POST with no future ID produces no entry. The future target and later `creationTag` are independent, non-atomic
 observations: the public API exposes neither an immutable project ID joined to the future nor a
 conditional DELETE. Cleanup rechecks type and `creationTag` immediately before deletion, rejecting
 detected key reuse, but cannot eliminate replacement in the remaining check-to-DELETE gap.
@@ -309,3 +331,15 @@ The `project-git` resource does not manage these settings, so public/auth-less a
 already-configured remotes are the supported automation paths.
 
 For fake-DSS smoke tests, return project lists as JSON arrays such as `[{ "projectKey": "MYPROJ", "name": "My Project" }]` from `/public/api/projects/`; recipe payload commands read `/public/api/projects/<PROJECT>/recipes/<NAME>?includePayload=true` and expect a JSON object shaped like `{ "recipe": { "name": "<NAME>", "type": "python" }, "payload": "..." }`.
+
+## License
+
+This project is source-available under the [Dataiku SDK Limited Use License 1.0](LICENSE), not an open-source license.
+
+- Individuals acting on their own behalf may use unmodified copies without a license fee.
+- Companies with total annual gross revenue below US $1,000,000 may use unmodified copies without a license fee.
+- Companies at or above that threshold, and all other entities, must request and obtain a separate written license before use.
+- Every modification, including private or internal changes, and every form of redistribution requires prior written approval.
+- Permitted use must preserve the license notices and display: `dataiku-sdk by clssck — https://github.com/clssck/dataiku-sdk`.
+
+Copies previously received under another license retain the rights granted for those copies. See [LICENSE](LICENSE) for the controlling terms and request path.

package/bin/dss.js

@@ -1,117 +1,87 @@
 #!/usr/bin/env node
+// npm bin for the dss CLI. Bun is the only runtime that executes CLI code.
+// A Node-launched npm shim only bootstraps Bun with automatic .env loading
+// disabled; `bunx --bun` enters Bun's Node-compatibility mode, which disables
+// that loading before this module runs.
 import { spawnSync, } from "node:child_process";
-import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath, pathToFileURL, } from "node:url";
 
-const args = process.argv.slice(2,);
-const optionArgs = args.includes("--",) ? args.slice(0, args.indexOf("--",),) : args;
-const here = path.dirname(fileURLToPath(import.meta.url,),);
-const distCliPath = path.resolve(here, "../dist/src/cli.js",);
-const sourceCliPath = path.resolve(here, "../src/cli.ts",);
-const cliPath = fs.existsSync(distCliPath,) ? distCliPath : sourceCliPath;
-const cliUrl = pathToFileURL(cliPath,).href;
+const runningUnderBun = typeof process.versions.bun === "string";
+const bunNodeCompatibilityMode = runningUnderBun
+	&& (
+		path.basename(process.argv0,).toLowerCase().startsWith("node",)
+		|| (
+			process.env.npm_lifecycle_event === "bunx"
+			&& ["dss", "dataiku-sdk",].includes(process.env.npm_lifecycle_script ?? "",)
+			&& /^bun(?:\.exe)?$/i.test(path.basename(process.env.npm_execpath ?? "",),)
+		)
+	);
+const envFileAutoloadDisabled = process.execArgv.includes("--no-env-file",)
+	|| bunNodeCompatibilityMode;
 
-function flagValue(names,) {
-	for (let i = 0; i < optionArgs.length; i++) {
-		const arg = optionArgs[i];
-		for (const name of names) {
-			if (arg === name) return optionArgs[i + 1];
-			if (arg.startsWith(`${name}=`,)) return arg.slice(name.length + 1,);
-		}
-	}
-	return undefined;
-}
-
-function hasFlag(names,) {
-	return names.some((name,) => optionArgs.includes(name,));
-}
-
-async function loadSavedTlsSettings() {
-	try {
-		const { loadCredentials, } = await import("../dist/src/config.js");
-		const creds = loadCredentials();
-		return {
-			caCertPath: creds?.caCertPath,
-			tlsRejectUnauthorized: creds?.tlsRejectUnauthorized,
-		};
-	} catch {
-		return {};
-	}
-}
-
-const savedTls = await loadSavedTlsSettings();
-const env = { ...process.env, };
-const explicitCaCert = flagValue(["--ca-cert", "--extra-ca-certs",],);
-if (explicitCaCert) {
-	env.NODE_EXTRA_CA_CERTS = explicitCaCert;
-} else if (!env.NODE_EXTRA_CA_CERTS && savedTls.caCertPath) {
-	env.NODE_EXTRA_CA_CERTS = savedTls.caCertPath;
-}
-
-if (hasFlag(["--insecure", "--skip-tls-verify",],)) {
-	env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
-} else if (
-	env.NODE_TLS_REJECT_UNAUTHORIZED === undefined && savedTls.tlsRejectUnauthorized === false
-) {
-	env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
-}
-const runningOnBun = Boolean(process.versions.bun,);
-const usesSourceCli = cliPath === sourceCliPath;
-
-// Published dist carries dist/build-metadata.json with the revision it was
-// built from. Forward it to the CLI so provenance can report dist source and
-// its build revision; only a full lowercase hexadecimal revision is accepted,
-// so an inherited or corrupt variable never stands in for packaged metadata.
-const distMetadataPath = path.resolve(here, "../dist/build-metadata.json",);
-if (!usesSourceCli) {
-	env.DSS_LOAD_SOURCE = "dist";
-	delete env.DSS_BUILD_REVISION;
-	try {
-		const metadata = JSON.parse(fs.readFileSync(distMetadataPath, "utf-8",),);
-		const revision = metadata.buildRevision;
-		if (typeof revision === "string" && /^[0-9a-f]{40}$/.test(revision,)) {
-			env.DSS_BUILD_REVISION = revision;
-		}
-	} catch {
-		// Dist without build metadata: provenance still reports dist source.
-	}
-}
-
-const runtimeBin = runningOnBun ? process.execPath : usesSourceCli ? "bun" : process.execPath;
-const runtimeArgs = runningOnBun || usesSourceCli ? ["--no-env-file",] : ["--use-system-ca",];
-const result = spawnSync(
-	runtimeBin,
-	[...runtimeArgs, cliPath, ...args,],
-	{
-		stdio: "inherit",
-		env,
-	},
-);
-
-if (result.error) {
-	const message = usesSourceCli
-		? `Unable to start Bun runtime for source dss CLI (${result.error.message}).`
-		: `Unable to start ${
-			runningOnBun ? "Bun" : "Node"
-		} runtime for packaged dss CLI (${result.error.message}); falling back to the current runtime.`;
-	if (usesSourceCli) {
+if (!runningUnderBun) {
+	const result = spawnSync(
+		"bun",
+		["--no-env-file", fileURLToPath(import.meta.url,), ...process.argv.slice(2,),],
+		{ stdio: "inherit", env: process.env, },
+	);
+	if (result.error) {
 		process.stdout.write(`${
 			JSON.stringify({
 				type: "error",
 				ok: false,
-				error: message,
+				error: "Unable to start the required Bun runtime.",
 				code: "internal_error",
 				category: "internal",
 				exitCode: 2,
+				hint: "Install Bun >= 1.4.0 and ensure `bun` is on PATH.",
 			},)
 		}\n`,);
 		process.exitCode = 2;
+	} else if (result.signal) {
+		process.kill(process.pid, result.signal,);
 	} else {
-		await import(cliUrl);
+		process.exitCode = result.status ?? 1;
 	}
-} else if (result.signal) {
-	process.kill(process.pid, result.signal,);
+} else if (!envFileAutoloadDisabled) {
+	process.stdout.write(`${
+		JSON.stringify({
+			type: "error",
+			ok: false,
+			error: "Bun automatic .env loading must be disabled for the dss launcher.",
+			code: "env_autoload_enabled",
+			category: "usage",
+			exitCode: 1,
+			hint: "Use `bunx --bun dataiku-sdk` or pass `--no-env-file` before the script path.",
+		},)
+	}\n`,);
+	process.exitCode = 1;
 } else {
-	process.exit(result.status ?? 1,);
+	const here = import.meta.dir;
+	const distCliPath = path.resolve(here, "../dist/src/cli.js",);
+	const sourceCliPath = path.resolve(here, "../src/cli.ts",);
+	const usesDistCli = await Bun.file(distCliPath,).exists();
+	const cliPath = usesDistCli ? distCliPath : sourceCliPath;
+
+	// Published dist carries dist/build-metadata.json with the revision it was
+	// built from. Hand it to the CLI so provenance can report dist source and its
+	// build revision; only a full lowercase hexadecimal revision is accepted, so an
+	// inherited or corrupt variable never stands in for packaged metadata.
+	if (usesDistCli) {
+		process.env.DSS_LOAD_SOURCE = "dist";
+		delete process.env.DSS_BUILD_REVISION;
+		try {
+			const metadata = await Bun.file(path.resolve(here, "../dist/build-metadata.json",),).json();
+			const revision = metadata.buildRevision;
+			if (typeof revision === "string" && /^[0-9a-f]{40}$/.test(revision,)) {
+				process.env.DSS_BUILD_REVISION = revision;
+			}
+		} catch {
+			// Dist without build metadata: provenance still reports dist source.
+		}
+	}
+
+	// Same process, same argv: the CLI sees process.argv.slice(2) exactly as before.
+	await import(pathToFileURL(cliPath,).href);
 }

package/dist/build-metadata.json

@@ -1 +1 @@
-{"format":1,"buildRevision":"70487e2275a70acce6862f126a89b1bc852ebb11"}
+{"format":1,"buildRevision":"894cf4823fd8a3ffb25cdaa93a09bcd222454565"}

package/dist/src/cli/commands/api-service.js

@@ -1,4 +1,3 @@
-import { writeFileSync, } from "node:fs";
 import { requiredJsonInput, } from "../coerce.js";
 import { requireArgs, UsageError, } from "../usage.js";
 export const apiServiceCommands = {
@@ -100,9 +99,11 @@ export const apiServiceCommands = {
             if (!out)
                 throw new UsageError("--output PATH is required.", "missing_required_flag");
             const res = await c.apiServices.downloadPackageArchive(a[0], a[1], f["project-key"]);
-            const buf = Buffer.from(await res.arrayBuffer());
-            writeFileSync(out, buf);
-            return { path: out, bytes: buf.length, };
+            if (!res.body) {
+                throw new Error("apiServices.downloadPackageArchive response did not include a body");
+            }
+            const bytes = await Bun.write(out, new Response(res.body), { createPath: false, });
+            return { path: out, bytes, };
         },
         usage: "dss api-service download-package <serviceId> <packageId> --output PATH [--project-key KEY]",
         description: "Download an API service package archive to a local file.",

package/dist/src/cli/commands/app.js

@@ -2,16 +2,17 @@ import { ClientValidationError, DataikuError, } from "../../errors.js";
 import { projectIncarnationHash, } from "../../utils/project-incarnation.js";
 import { jsonInput, num, parseBooleanOption, plainRecord, requiredJsonInput, requiredStringFlag, stringField, } from "../coerce.js";
 import { appPermissionsHash, appPermissionsVerificationError, assertAppPermissionsSnapshotBinding, buildAppPermissionsSnapshot, diffAppPermissions, readAppPermissionsSnapshot, writeAppPermissionsSnapshot, } from "../helpers/app-permissions.js";
-import { createSuccessorInstance, futureTargetIdentity, isDefinitiveRejection, requireAbsentProjectTarget, safeErrorSummary, verifyAppInstance, VISUAL_UI_GATE, } from "../helpers/app-successor.js";
+import { createSuccessorInstance, futureTargetIdentity, isDefinitiveRejection, preflightSuccessorInstance, requireAbsentProjectTarget, safeErrorSummary, verifyAppInstance, VISUAL_UI_GATE, } from "../helpers/app-successor.js";
 import { CommandResultFailure, } from "../output.js";
 import { requireArgs, requireNoArgs, UsageError, } from "../usage.js";
 const CREATE_INSTANCE_USAGE = "dss app create-instance <appId> (--data JSON|--data-file PATH|--stdin) [--wait] [--timeout MS] [--poll-interval MS]";
 const MANIFEST_VERSION_USAGE = "dss app manifest-version [--project-key KEY]";
 const SET_MANIFEST_VERSION_USAGE = "dss app set-manifest-version (--manifest-version V|--version-notes NOTES) [--expect-hash SHA256] [--dry-run] [--project-key KEY]";
 const CREATE_SUCCESSOR_USAGE = "dss app create-successor-instance <appId> --from KEY --to KEY [--name NAME] [--copy-permissions] [--timeout MS] [--poll-interval MS] [--dry-run] [--record-cleanup PATH]";
+const SUCCESSOR_PREFLIGHT_USAGE = "dss app successor-preflight <appId> --from KEY --to KEY [--name NAME] [--copy-permissions]";
 const VERIFY_INSTANCE_USAGE = "dss app verify-instance <appId> --project-key KEY [--expect-version V]";
 const DELETE_INSTANCE_USAGE = "dss app delete-instance --project-key KEY [--future-id ID] [--expect-project-incarnation SHA256] [--unconfirmed-creation] [--timeout MS] [--poll-interval MS]";
-const CREATE_INSTANCE_INDETERMINATE_REMEDIATION = "DSS may have accepted the creation, but no future ID proves when it settles. The recorded cleanup entry intentionally stops as unresolved; inspect `dss app instances <appId>` and retry deletion only after creation is known terminal.";
+const CREATE_INSTANCE_INDETERMINATE_REMEDIATION = "DSS may have accepted the creation, but no future ID or project incarnation authorizes cleanup. Inspect `dss app instances <appId>` and DSS task history; delete only after creation is known terminal and the target identity is verified.";
 const CREATE_INSTANCE_REJECTED_REMEDIATION = "DSS refused the creation request, so no instance project was created: fix the reported problem and retry.";
 const DELETE_INSTANCE_FUTURE_REMEDIATION = "The supplied creation future could not authorize deletion. Inspect that future and the target project, then retry only with a future whose terminal result reports this project.";
 const DELETE_INSTANCE_UNCONFIRMED_REMEDIATION = "Creation may still be running and DSS returned no future ID. Inspect the app's instances and wait until creation is known terminal before running delete-instance without --unconfirmed-creation.";
@@ -116,7 +117,9 @@ export const appCommands = {
                 throw new UsageError("Instance creation payload must include a non-empty targetProjectKey.", "validation_failed", `Usage: ${CREATE_INSTANCE_USAGE}`);
             }
             body.targetProjectKey = requestedProjectKey;
-            await requireAbsentProjectTarget(c, requestedProjectKey, "targetProjectKey");
+            await requireAbsentProjectTarget(c, requestedProjectKey, "targetProjectKey", {
+                appId: a[0],
+            });
             let created;
             try {
                 created = await c.applications.createInstance(a[0], body);
@@ -124,15 +127,19 @@ export const appCommands = {
             catch (error) {
                 // A definitive rejection proves nothing was created; anything else
                 // (5xx, retryable 4xx, transport failure) leaves the outcome
-                // unknown and stays cleanup-eligible against the requested key.
+                // unknown. Without a returned future ID or verified incarnation,
+                // cleanup cannot be authorized.
                 const rejected = isDefinitiveRejection(error);
                 return {
                     success: false,
-                    state: "CREATE_FAILED",
+                    state: rejected ? "CREATE_FAILED" : "INDETERMINATE",
                     elapsedMs: 0,
                     pollCount: 0,
                     projectKey: requestedProjectKey,
-                    cleanupEligible: !rejected,
+                    outcome: rejected ? "rejected" : "indeterminate",
+                    creationPostAttempted: true,
+                    cleanupEligible: false,
+                    recoveryCommands: rejected ? [] : [`dss app instances ${a[0]}`,],
                     remediation: rejected
                         ? CREATE_INSTANCE_REJECTED_REMEDIATION
                         : CREATE_INSTANCE_INDETERMINATE_REMEDIATION,
@@ -143,11 +150,13 @@ export const appCommands = {
             if (!instance) {
                 return {
                     success: false,
-                    state: "UNTRACKABLE",
+                    state: "INDETERMINATE",
                     elapsedMs: 0,
                     pollCount: 0,
                     projectKey: requestedProjectKey,
-                    cleanupEligible: true,
+                    outcome: "indeterminate",
+                    creationPostAttempted: true,
+                    cleanupEligible: false,
                     responseKind: created === undefined
                         ? "empty"
                         : created === null
@@ -157,6 +166,7 @@ export const appCommands = {
                                 : "scalar",
                     error: "DSS accepted instance creation without returning a structured creation state.",
                     remediation: CREATE_INSTANCE_INDETERMINATE_REMEDIATION,
+                    recoveryCommands: [`dss app instances ${a[0]}`,],
                 };
             }
             // The create endpoint's `jobId` is a DSS future ID (the official client wraps it in
@@ -174,7 +184,7 @@ export const appCommands = {
                     projectKey: requestedProjectKey,
                     instance,
                     ...(jobId !== undefined ? { futureId: jobId, jobId, } : {}),
-                    cleanupEligible: true,
+                    cleanupEligible: jobId !== undefined,
                     error: "DSS named a different target project in the creation response.",
                     expected: { projectKey: requestedProjectKey, },
                     actual: { projectKey: echoedTarget, },
@@ -251,14 +261,17 @@ export const appCommands = {
             if (!jobId) {
                 return {
                     success: false,
-                    state: "UNTRACKABLE",
+                    state: "INDETERMINATE",
                     elapsedMs: 0,
                     pollCount: 0,
                     projectKey: requestedProjectKey,
                     instance,
-                    cleanupEligible: true,
-                    error: "DSS returned no instance-creation future ID. The instance may still have been created; inspect app instances or replay the recorded cleanup entry.",
+                    outcome: "indeterminate",
+                    creationPostAttempted: true,
+                    cleanupEligible: false,
+                    error: "DSS returned no instance-creation future ID. The instance may still have been created; inspect app instances before any recovery action.",
                     remediation: CREATE_INSTANCE_INDETERMINATE_REMEDIATION,
+                    recoveryCommands: [`dss app instances ${a[0]}`,],
                 };
             }
             let waited;
@@ -278,6 +291,7 @@ export const appCommands = {
                     instance,
                     jobId,
                     cleanupEligible: true,
+                    recoveryCommands: [`dss future wait ${jobId}`, `dss app instances ${a[0]}`,],
                     remediation: CREATE_INSTANCE_INDETERMINATE_REMEDIATION,
                     ...safeErrorSummary(error),
                 };
@@ -343,6 +357,25 @@ export const appCommands = {
             'dss app create-instance my-app --data \'{"targetProjectKey":"NEWPROJ"}\' --wait --timeout 120000 --poll-interval 2000',
         ],
     },
+    "successor-preflight": {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, SUCCESSOR_PREFLIGHT_USAGE);
+            return preflightSuccessorInstance(c, {
+                appId: a[0],
+                from: requiredStringFlag(f, "from", SUCCESSOR_PREFLIGHT_USAGE),
+                to: requiredStringFlag(f, "to", SUCCESSOR_PREFLIGHT_USAGE),
+                ...(f["name"] !== undefined ? { name: f["name"], } : {}),
+                copyPermissions: parseBooleanOption(f["copy-permissions"], "--copy-permissions") ?? false,
+                dryRun: true,
+            }, SUCCESSOR_PREFLIGHT_USAGE);
+        },
+        usage: SUCCESSOR_PREFLIGHT_USAGE,
+        description: "Run every read-only successor gate before changing the template version: validate the template, verify the predecessor, prove target absence, and optionally snapshot the predecessor ACL.",
+        examples: [
+            "dss app successor-preflight my-app --from OLD_INSTANCE --to NEW_INSTANCE",
+            "dss app successor-preflight my-app --from OLD_INSTANCE --to NEW_INSTANCE --copy-permissions",
+        ],
+    },
     "create-successor-instance": {
         handler: async (c, a, f) => {
             requireArgs(a, 1, CREATE_SUCCESSOR_USAGE);

package/dist/src/cli/commands/bundle.js

@@ -1,4 +1,3 @@
-import { writeFileSync, } from "node:fs";
 import { requireArgs, UsageError, } from "../usage.js";
 export const bundleCommands = {
     "list-exported": {
@@ -34,9 +33,11 @@ export const bundleCommands = {
             if (!out)
                 throw new UsageError("--output PATH is required.", "missing_required_flag");
             const res = await c.bundles.downloadExportedArchive(a[0], f["project-key"]);
-            const buf = Buffer.from(await res.arrayBuffer());
-            writeFileSync(out, buf);
-            return { path: out, bytes: buf.length, };
+            if (!res.body) {
+                throw new Error("bundles.downloadExportedArchive response did not include a body");
+            }
+            const bytes = await Bun.write(out, new Response(res.body), { createPath: false, });
+            return { path: out, bytes, };
         },
         usage: "dss bundle download-exported <bundleId> --output PATH [--project-key KEY]",
         description: "Download an exported Design-node bundle archive to a local file.",

package/dist/src/cli/commands/project-library.js

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync, } from "node:fs";
+import * as fs from "node:fs";
 import { readStdinText, } from "../coerce.js";
 import { encodedProjectEndpoint, planResult, } from "../output.js";
 import { requireArgs, UsageError, } from "../usage.js";
@@ -68,8 +68,8 @@ export const projectLibraryCommands = {
             if (!out)
                 throw new UsageError("--output PATH is required.", "missing_required_flag");
             const bytes = await c.projectLibrary.getFileBytes(a[0], f["project-key"]);
-            writeFileSync(out, bytes);
-            return { path: out, bytes: bytes.length, };
+            const written = await Bun.write(out, bytes, { createPath: false, });
+            return { path: out, bytes: written, };
         },
         usage: "dss project-library get-bytes <path> --output PATH [--project-key KEY]",
         description: "Download a project library file's raw bytes to a local file.",
@@ -126,7 +126,7 @@ export const projectLibraryCommands = {
             const content = typeof f["content"] === "string"
                 ? f["content"]
                 : typeof f["file"] === "string"
-                    ? readFileSync(f["file"], "utf-8")
+                    ? fs.readFileSync(f["file"], "utf-8")
                     : await readStdinText();
             await c.projectLibrary.addOrUpdateFile(a[0], content, pk);
             return { updated: a[0], };