Projects API

Classes

Project discovery, creation, mutations and files.

projects.update(id, { pinned, archived }) sets or clears pinnedAt and archivedAt on servers that advertise the projectOrganization environment capability; older servers drop both fields. Archiving keeps threads and files, and projects.list still returns an archived project with its archivedAt.

Project repository identities can include origin.remoteUrl, an optional trimmed nonempty string naming the checkout remote when its repository differs from the canonical repository. Omission does not imply a missing remote.

projects.files.read({ cwd, relativePath, allowMissing: true }) returns empty contents, zero byteLength, truncated false and exists: false for an absent file. Omitted or false allowMissing retains the missing-file error. The optional boolean result field exists can be omitted by the server; omission does not mean that the file is absent.

projects.files.listIgnored({ cwd }) lists the untracked files git ignores under cwd, each with a trimmed nonempty path and a nonnegative integer byteLength. The server leaves out wholly ignored folders and ignored symbolic links, and caps the list; truncated is true when more files matched than it returned. A directory outside a repository returns no files. A malformed file entry is left out and the other entries remain. A missing or non-directory cwd fails with ProjectListEntriesError.

ProjectsApi

Project discovery, creation, mutations and files.

Kind: global class

ProjectsApi

projectsApi.list()

List active project summaries from the shell snapshot.

async list(signal?: AbortSignal): Promise<OrchestrationProjectShell[]>;

Kind: instance method of ProjectsApi

projectsApi.snapshot()

The full project records over GET /api/projects.

snapshot(signal?: AbortSignal): Promise<ProjectSnapshot>;

Kind: instance method of ProjectsApi

projectsApi.get()

Find a project summary by id; return undefined when absent.

async get(
    projectId: ProjectId,
    signal?: AbortSignal,
  ): Promise<OrchestrationProjectShell | undefined>;

Kind: instance method of ProjectsApi

projectsApi.findByWorkspaceRoot()

Find a project using its normalized absolute workspace root.

async findByWorkspaceRoot(
    workspaceRoot: string,
    signal?: AbortSignal,
  ): Promise<OrchestrationProjectShell | undefined>;

Kind: instance method of ProjectsApi

projectsApi.create()

Create a project with a generated id unless the caller supplies one.

create(input: ProjectCreateInput, signal?: AbortSignal): Promise<Project>;

Kind: instance method of ProjectsApi

projectsApi.ensure()

Finds the project for workspaceRoot or creates it; renames it only when the title differs.

async ensure(
    input: ProjectEnsureInput,
    signal?: AbortSignal,
  ): Promise<OrchestrationProjectShell>;

Kind: instance method of ProjectsApi

projectsApi.ensureScratch()

Finds or creates the environment’s Scratch project, rooted at ServerConfig.scratchWorkspaceRoot. Fails with OrchestrationDispatchCommandError when the server offers no Scratch folder.

ensureScratch(signal?: AbortSignal): Promise<ProjectEnsureScratchResult>;

Kind: instance method of ProjectsApi

projectsApi.createNew()

Creates a project from just a name: the server makes a folder under ServerConfig.newProjectsRoot with a first commit, then the project. commitError says why the commit failed; the project exists either way.

createNew(input: ProjectCreateNewInput, signal?: AbortSignal): Promise<ProjectCreateNewResult>;

Kind: instance method of ProjectsApi

projectsApi.createFromThread()

Turns a No project thread’s own folder into a project, in place, and moves every thread working in that folder into it. Calling it again finishes a partial move. Fails with OrchestrationDispatchCommandError when the thread has no own Scratch folder or a thread to move still has work in progress. Servers advertise this with the threadProjectFromScratch environment capability.

createFromThread(
    input: ProjectCreateFromThreadInput,
    signal?: AbortSignal,
  ): Promise<ProjectCreateFromThreadResult>;

Kind: instance method of ProjectsApi

projectsApi.update()

Update the selected project metadata.

update(projectId: ProjectId, patch: ProjectMetaUpdate, signal?: AbortSignal): Promise<Project>;

Kind: instance method of ProjectsApi

projectsApi.delete()

Resolves when the project is gone, including when it never existed.

async delete(
    projectId: ProjectId,
    options: { readonly force?: boolean } = {},
    signal?: AbortSignal,
  ): Promise<void>;

Kind: instance method of ProjectsApi