WSM includes an embedded JavaScript runtime (goja). Scripts can call workspace operations through require("wsm") without shelling out to CLI subcommands.

Running Scripts

wsm runner my-script.js

Control result printing:

wsm runner my-script.js --print-result=false

Use machine-oriented rows:

wsm runner my-script.js --output-mode data --output json --print-result=false

Module Overview

Inside runner scripts:

const wsm = require("wsm");
const manager = wsm.createManager({ defaultJobs: 8 });

Top-level exports:

Manager options:

Manager API Surface

Flat manager methods:

Namespaced aliases:

Flat and namespaced methods route to shared closures in module code, so behavior stays aligned.

Workspace Handle API

Load and operate in a workspace-scoped context:

const ws = manager.loadWorkspace("my-workspace");
const info = ws.info();
const log = ws.git.log({ limit: 20, oneline: true });

Handle methods:

Common Inputs

Examples (camelCase keys):

manager.discover({ paths: ["/work/repos"], recursive: true, maxDepth: 3 });

manager.createWorkspace({
  name: "ws-api-demo",
  repos: ["repo1", "repo2"],
  branchPrefix: "feat",
  dryRun: false,
});

manager.workspaces.add({
  workspaceName: "ws-api-demo",
  repoName: "repo3",
  force: true,
});

manager.git.commit({
  workspaceName: "ws-api-demo",
  message: "Apply coordinated update",
  addAll: true,
  push: false,
});

Error and Batch Semantics

Validation errors are thrown as JS TypeError before workflow execution for required fields, for example:

• createWorkspace requires name and repos.
• workspaces.add requires workspaceName and repoName.
• workspaces.merge requires workspaceName.
• git.commit requires message or template.
• git.branch.create/switch require branchName.

Execution failures (workspace not found, git failures, etc.) throw regular JS errors from Go workflow/service errors.

Batch-oriented operations return arrays/rows rather than throwing per repository row failure. Row objects contain success/error signals, for example:

• branch operations: results[] with repository-level success and error.
• rebase status/action: rows[] with repository-level state or action result.

Type Contract

Completion-level declarations are maintained in:

• pkg/wsmjs/spec/wsm.d.ts.tmpl
• pkg/wsmjs/spec/wsm.d.ts (generated snapshot)

Regenerate and validate with:

go generate ./pkg/wsmjs/spec
go test ./pkg/wsmjs/spec

Example Script

const wsm = require("wsm");
const manager = wsm.createManager({ defaultJobs: 4 });

const repos = manager.registry.listRepositories({});
const workspaces = manager.registry.listWorkspaces();

({
  ok: true,
  version: wsm.version,
  repositories: repos.length,
  workspaces: workspaces.length,
  remote: wsm.consts.remote.ORIGIN,
});

Troubleshooting

See Also

• wsm help wsm-command-reference
• wsm help wsm-architecture-overview
• wsm help wsm-troubleshooting