workspace: add artifacts interface to worker backend

[aron-cf]

This pull request adds first-class Cloudflare Artifacts support to @cloudflare/workspace. A worker can now wrap an ARTIFACTS binding with createArtifact(binding, sessionId) and work with local repository names while the library handles session scoping. That gives each agent, task, or user its own isolated set of repositories inside the same Artifacts namespace.

The new client covers the repository and token lifecycle: create, get, list, import, delete, create token, list tokens, get token metadata, and revoke token. Repository names are scoped before they touch the binding and unscoped before they come back to the caller. The scoped name uses a legal Artifacts repository name, such as session123__build-cache, while callers continue to pass and receive build-cache.

import { createArtifact } from "@cloudflare/workspace/artifacts";

const artifacts = createArtifact(env.ARTIFACTS, ctx.id.toString());

const repo = await artifacts.create("build-cache", {
  description: "Cached build output for this run",
  setDefaultBranch: "main",
});

console.log(repo.name); // "build-cache"
console.log(repo.remote); // Git remote for the scoped Artifacts repo

const token = await artifacts.createToken("build-cache", "read", 3600);
console.log(token.plaintext); // Capture this once. It is not returned by list/get.

const repos = await artifacts.list();
// Repos from other sessions in the same namespace are filtered out.

The same implementation is also available as an argv-style interface. That gives shell users and agents a stable command surface with machine-readable JSON output and predictable exit codes.

const result = await artifacts.cli({
  argv: ["repo", "create", "build-cache", "--description", "CI output"],
});

if (result.exitCode !== 0) {
  throw new Error(result.stderr);
}

const created = JSON.parse(result.stdout);

The worker backend can expose that CLI as an opt-in artifacts shell command. The command is not registered globally because the Artifacts binding belongs to the consuming worker, not to the workspace package itself.

import { ShellWorker, defineArtifactsCommand } from "@cloudflare/workspace/backends/worker";
import { createArtifact } from "@cloudflare/workspace/artifacts";
import type { CustomCommand } from "just-bash";

export class MyShell extends ShellWorker<Env> {
  protected override extraCommands(): CustomCommand[] {
    const artifacts = createArtifact(this.env.ARTIFACTS, this.env.SESSION_ID);
    return [defineArtifactsCommand({ artifacts })];
  }
}

With that command registered, code running through bash.exec can call the same surface directly:

artifacts repo create build-cache --description "CI output"
artifacts repo list
artifacts token create build-cache --scope read --ttl 3600

The implementation uses the global Cloudflare Workers Artifacts types from @cloudflare/workers-types instead of redeclaring the binding shape. The in-memory fake used by tests implements the same Artifacts interface and validates repository names against the binding's documented character set, so tests catch shape drift and invalid scoped names.

The CLI is designed to be safe for agents and logs. token create is the only token command that prints plaintext. token list, token get, and token revocation print metadata or a constant confirmation, so a caller does not accidentally echo a secret while revoking by plaintext.

Documentation is included in docs/14_artifacts_interface.md, with cross-links from the workspace docs and package README. The examples/think worker now shows optional typed Artifacts integration: it detects an ARTIFACTS binding when configured and returns an empty list when the binding is absent, so the example still runs without Artifacts.

Validation run:

npm run format
npx biome check .
npx vitest run src/artifacts/ src/backends/worker/artifacts-command.test.ts
npm test --workspace @cloudflare/workspace
npm run build --workspace @cloudflare/workspace
npm run typecheck --workspace @cloudflare/example-think

A filtered npm test --workspace @cloudflare/workspace -- src/artifacts/ ... command is not a useful shortcut for this package because the package test script forwards the filter to every Vitest config, including configs whose include patterns do not contain those files. The unfiltered workspace package test passes.