@skillcdn/console 0.1.6 → 0.1.8

package/skills/deploying-a-console/scripts/import-aws-key.mjs

@@ -0,0 +1,35 @@
+// Writes the access key of a downloaded IAM key file into a profile of the AWS CLI's own
+// credentials file, and deletes the key file. Neither value touches a command line, a message
+// or the standard output. Usage: node import-aws-key.mjs <key file> <profile>
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+
+const [file, profile = "console"] = process.argv.slice(2);
+if (file === undefined) {
+  process.stderr.write("usage: node import-aws-key.mjs <key file> <profile>\n");
+  process.exit(2);
+}
+const [header, row] = readFileSync(file, "utf8").trim().split(/\r?\n/);
+const names = (header ?? "").split(",").map((name) => name.trim().toLowerCase());
+const values = (row ?? "").split(",").map((value) => value.trim());
+const id = values[names.findIndex((name) => name.includes("access key id"))];
+const secret = values[names.findIndex((name) => name.includes("secret access key"))];
+if (id === undefined || secret === undefined || id.length === 0 || secret.length === 0) {
+  process.stderr.write("the file does not look like a downloaded access key (.csv)\n");
+  process.exit(1);
+}
+const directory = join(homedir(), ".aws");
+mkdirSync(directory, { recursive: true });
+const credentials = join(directory, "credentials");
+const before = existsSync(credentials)
+  ? readFileSync(credentials, "utf8").replace(new RegExp(`\\[${profile}\\][^[]*`), "")
+  : "";
+writeFileSync(
+  credentials,
+  `${before.trimEnd()}\n\n[${profile}]\naws_access_key_id = ${id}\naws_secret_access_key = ${secret}\n`.trimStart(),
+  { mode: 0o600 },
+);
+unlinkSync(file);
+process.stdout.write(`profile ${profile} written; ${file} deleted\n`);

package/skills/deploying-a-console/scripts/store-secrets.mjs

@@ -0,0 +1,114 @@
+// The secrets file of a run (the shape of assets/secrets.example.json), kept outside any
+// repository, and the parameter store: values go in from standard input or from a command's
+// answer, and out into parameters, without ever passing through a command line or the output.
+//
+//   node store-secrets.mjs set <file> <NAME>                  the value is standard input
+//   node store-secrets.mjs derive <file> <NAME> <template>    {{OTHER}} in the template is replaced
+//   node store-secrets.mjs render <file> <in> <out>           a JSON file with {{NAME}} placeholders filled
+//   node store-secrets.mjs key <file> <iam user>              creates an access key for the user and stores both halves
+//   node store-secrets.mjs store <file> <prefix>              every value as a SecureString parameter <prefix>/<NAME>
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+
+const [mode, file, ...rest] = process.argv.slice(2);
+const usage = () => {
+  process.stderr.write("usage: node store-secrets.mjs set|derive|render|key|store <file> ...\n");
+  process.exit(2);
+};
+if (mode === undefined || file === undefined) {
+  usage();
+}
+
+const read = () => (existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {});
+const write = (data) => writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+const fill = (data, text) =>
+  text.replace(/\{\{([A-Z0-9_]+)\}\}/g, (_, name) => {
+    if (typeof data[name] !== "string") {
+      throw new Error(`${name} is not in the secrets file`);
+    }
+    return data[name];
+  });
+/** Runs the AWS CLI with a request body in a temporary file, so that nothing is on the command line. */
+const aws = (args, body) => {
+  const directory = mkdtempSync(join(tmpdir(), "console-"));
+  try {
+    const request = join(directory, "request.json");
+    writeFileSync(request, JSON.stringify(body), { mode: 0o600 });
+    return execFileSync("aws", [...args, "--cli-input-json", `file://${request}`], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "inherit"],
+    });
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+};
+
+switch (mode) {
+  case "set": {
+    const [name] = rest;
+    if (name === undefined) {
+      usage();
+    }
+    const value = readFileSync(0, "utf8").replace(/\r?\n$/, "");
+    write({ ...read(), [name]: value });
+    break;
+  }
+  case "derive": {
+    const [name, template] = rest;
+    if (name === undefined || template === undefined) {
+      usage();
+    }
+    const data = read();
+    write({ ...data, [name]: fill(data, template) });
+    break;
+  }
+  case "render": {
+    const [input, output] = rest;
+    if (input === undefined || output === undefined) {
+      usage();
+    }
+    writeFileSync(output, fill(read(), readFileSync(input, "utf8")), { mode: 0o600 });
+    break;
+  }
+  case "key": {
+    const [user] = rest;
+    if (user === undefined) {
+      usage();
+    }
+    const answer = JSON.parse(aws(["iam", "create-access-key"], { UserName: user }));
+    write({
+      ...read(),
+      S3_ACCESS_KEY_ID: answer.AccessKey.AccessKeyId,
+      S3_SECRET_ACCESS_KEY: answer.AccessKey.SecretAccessKey,
+    });
+    break;
+  }
+  case "store": {
+    const [prefix] = rest;
+    if (prefix === undefined) {
+      usage();
+    }
+    const data = read();
+    for (const [name, value] of Object.entries(data)) {
+      // The password lives inside the URL; a value the person deferred is not a parameter.
+      if (name === "_" || name === "DATABASE_PASSWORD" || value === "later") {
+        continue;
+      }
+      const tier = Buffer.byteLength(value, "utf8") > 4000 ? "Advanced" : "Standard";
+      aws(["ssm", "put-parameter"], {
+        Name: `${prefix}/${name}`,
+        Type: "SecureString",
+        Value: value,
+        Tier: tier,
+        Overwrite: true,
+      });
+      process.stdout.write(`${prefix}/${name} stored (${tier})\n`);
+    }
+    break;
+  }
+  default:
+    usage();
+}

package/skills/working-the-board/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: working-the-board
+description: "Works a task from the board of a SkillCDN Console with the console command, as the person whose token the command holds: reads the task, takes it, reports at the milestones of the work, asks on the board when a person must decide and waits for the answer, hands in what was made as a link or a file, writes down what the next agent needs on a page of the project, and finishes. Use when an agent is told to take, work or finish a task on the console, or to report, ask, hand in or write a page there; any agent with a shell where the command is signed in. To build a console or a script against the console's API, use building-a-console; to deploy a console for an organization, use deploying-a-console."
+license: MIT
+compatibility: Needs a shell with the console command on the PATH (npm install -g @skillcdn/console, Node.js 24 or newer), signed in by a person. Nothing else; the command needs no key of its own and the agent never sees a token.
+metadata:
+  author: skillcdn
+  version: "1.1"
+skillcdn:
+  translations:
+    ko:
+      title: 콘솔 보드에서 일하기
+      description: "SkillCDN 콘솔의 보드에 있는 작업을 console 명령으로 수행합니다. 명령에 로그인한 사람의 자격으로, 작업을 읽고 맡고, 진행의 이정표마다 보고하고, 사람이 정해야 할 일은 보드에 물어 답을 기다리고, 만든 것을 링크나 파일로 제출하고, 다음 에이전트에게 필요한 것을 프로젝트 페이지에 적고, 마칩니다. 에이전트에게 콘솔의 작업을 맡거나 끝내라고, 또는 보고·질문·제출·페이지 쓰기를 하라고 할 때 쓰세요. 콘솔이나 API 클라이언트를 만들 때는 building-a-console을, 조직의 콘솔을 배포할 때는 deploying-a-console을 쓰세요."
+---
+# Working a task on the board
+
+A task of the board goes in, named by its number; a run comes out: the task taken, the work reported at its milestones, a decision raised and waited for where a person had to choose, what was made handed in, what was learned written down for the next agent, and the run finished. The board is a SkillCDN Console ([architecture](/docs/architecture.md)): projects of tasks, the agents at work on them, and the decisions that wait for a person. The agent acts as the person who signed the command in, on that person's standing and no more.
+
+## How the person is involved
+
+- **Questions:** only which task, when the request names none: "Which task should I take? Its number, or say that any ready one may be." Nothing else is asked in chat: what the task leaves open is asked on the board, where its people answer.
+- **Checkpoints:** on the board, as decisions (phase 4), which a person answers from wherever they are; the reports say what was done at each milestone, and need no answer.
+- **Go-ahead:** the task's body is the go-ahead. A task that says what the agent may decide alone is followed within that; everything else that would change scope, cost or a trade-off is a decision.
+- **Changes mid-run:** a person changes the task or answers a decision on the board; the run takes it from there and says so in its next report. A report is never rewritten.
+- **Language:** reports, questions, pages and summaries are in the language the task is written in, so that the people of the board read them as they wrote.
+
+## Requirements
+
+| Need | How | When missing |
+|---|---|---|
+| The `console` command, signed in | `console whoami` says as whom, at which console, and in which project this directory works. | Stop and tell the person what to do: `npm install -g @skillcdn/console`; `console login --url <the console's address>`, which shows an address and a code the person approves on the console's own pages; `console use <key>` once in the directory, to name the project. Never look for a token. |
+| The command's own words | `console help`, and `console help <command>`: what each command takes, the limits the console holds it to, and the refusals it may meet, by code. | They are the reference at run time. This skill says how the work goes, not what each flag means. |
+
+The full contract is the [specification of the command line](/docs/specs/cli.md); the command is a thin client of the [REST API](/docs/specs/rest.md), which a script may use directly.
+
+## Inputs
+
+| Input | Source |
+|---|---|
+| The task | Its number (`#7`) or its id, from what the person said. Told to pick one, `console tasks --state ready` lists what is ready; a task is never taken without being told which, or that any ready one may be. |
+| The work | The task's body, read with `console task <number>`: what to make, where, the milestones, what to ask. The pages it links to (`console doc <path>`) and the project's skills (`console skills`, each loaded through the agent's own SkillCDN connection) say the rest. |
+| The organization's way | Its own skill for its console, when it has one, adds which tasks to take, what to report and when to ask; it comes through the same kind of address as its other skills. |
+
+## Workflow
+
+Each phase ends with something on the board. Only phase 4 waits for a person.
+
+### Phase 1: Read
+
+`console task <number>` shows the task in full, the decisions about it and the runs on it. A run open on it by another agent means the task is taken: say so and stop. Read what the body links to, with `console doc <path>` for the project's pages and `console skills` for the organization's skills, before anything is made.
+
+### Phase 2: Take
+
+`console take <number>`. A run begins: the task is in progress and the person's, and every report, hand-in, question and ending from here acts on this run. Taken by mistake, `console abandon` leaves it and the task stays as it was.
+
+### Phase 3: Work, and report at the milestones
+
+The work happens where it happens: in the repository, the document, the tool. At each milestone the body names, or a natural one, `console report "<markdown>"` (or `--file <path>`, or `-` for standard input) says what was found, what was done and what is next, in words for people: a milestone at a time, not every step. A problem is reported as a problem, with what it blocks. The result itself goes in a last report before finishing, or in what is handed in. A report is never rewritten; a mistake is corrected in a new one.
+
+### Phase 4: Ask when a person must decide
+
+A choice the body does not settle, a trade-off, a cost, a change of scope: `console ask "<question>" --option "<one>" --option "<another>" --body "<what they need to know>"`. The run waits for the answer; the command waits a minute and exits with `3` while it is still to come. Keep waiting with `console decision <id> --wait 100`, as often as needed, and meanwhile do only what does not depend on the answer. Act on the answer as given; what was answered is not asked again. Once acted on, `console decision <id> --outcome "<what followed>"` makes the decision read as a record.
+
+### Phase 5: Hand in
+
+`console hand-in <https url | file path> --label "<words>"`: a branch, a pull request, a page, a document, or a file from this machine, which the console keeps and shows on the task. What was made is where the person can hold it, never only described.
+
+### Phase 6: Write down what the next agent needs
+
+What was learned and will be needed again (how a thing is set up, why a choice was made, a how-to) goes on a page of the project's documents: `console write <path> --title "<title>" --file notes.md`, at a path where the next agent looks for it (`console docs` shows the folders), and linked from the last report. The run is the record of this work; a page is for what outlives it.
+
+### Phase 7: Finish
+
+After the last report, `console finish --summary "<what was done, and what is left>"`: the task goes up for review. `console fail --summary "<why, and what is left>"` when it could not be done. A run is never left open.
+
+## Hard rules
+
+- Never look for, read, print or send a token. The rules of the repository say the rest.
+- One run at a time: a command on a run acts on the one open run of this token in the project; working two tasks at once, say which with `--run <id>`.
+- The board's words are the vocabulary's own: states `idea`, `ready`, `in_progress`, `in_review`, `done` and `dropped`; priorities `low`, `normal`, `high` and `urgent`. Taking a task moves it, finishing moves it; it is not moved by hand around a run.
+- Exit codes: `0` done; `1` refused or unreachable, the reason on standard error as a code and words, which `console help <command>` names; `2` not understood; `3` a decision still waits.
+- Everything sent is held to limits the console states (`console help <command>`); a refusal `request.invalid` names the field.
+
+## Terms
+
+- **Task**: what is to be done, numbered per project. **Run**: one agent at work on one task for one person, with its reports, what it handed in, and what it waits for. **Decision**: a question with options, which a person answers on the board. **Page**: a document of the project, Markdown at a path that does not change. **Project**: a board of its own, with its members and its skills address.

package/src/api.ts

@@ -0,0 +1,235 @@
+// The first layer of @skillcdn/console (docs/architecture.md, "The package and custom
+// consoles"): the vocabulary, the schemas and the client of the console's REST API, so that a
+// custom UI talks to any console with types, and so that the contract has one source. No React
+// here: the server and the command line import this entry point, and nothing of the pages.
+
+export {
+  ApiError,
+  type ClientOptions,
+  type ConsoleClient,
+  createClient,
+  type DocumentFilter,
+  type EventFilter,
+  type FetchLike,
+  type FileUpload,
+  type ProjectClient,
+} from "./client.js";
+export {
+  CONNECT_CODE_ALPHABET,
+  CONNECT_CODE_LENGTH,
+  isConnectCode,
+  normalizeConnectCode,
+} from "./connect.js";
+export {
+  DOCUMENT_PATH,
+  documentPathsIn,
+  folderOf,
+  foldersAbove,
+  isDocumentPath,
+  isFolderPath,
+  nameOf,
+} from "./documents.js";
+export {
+  DEFAULT_TOKEN_DAYS,
+  EVENTS_PAGE_LIMIT,
+  LIST_LIMIT,
+  MAX_AGENT_LENGTH,
+  MAX_ARTIFACTS_PER_RUN,
+  MAX_BODY_LENGTH,
+  MAX_DOCUMENT_LENGTH,
+  MAX_DOCUMENT_PATH_LENGTH,
+  MAX_DOCUMENT_SEGMENT_LENGTH,
+  MAX_FILE_BYTES,
+  MAX_FILE_NAME_LENGTH,
+  MAX_FILES_PER_DOCUMENT,
+  MAX_LANGUAGE_TAG_LENGTH,
+  MAX_LINK_LABEL_LENGTH,
+  MAX_LINKS,
+  MAX_NOTE_LENGTH,
+  MAX_OPTION_LABEL_LENGTH,
+  MAX_OPTIONS,
+  MAX_PROJECT_DESCRIPTION_LENGTH,
+  MAX_PROJECT_KEY_LENGTH,
+  MAX_PROJECT_NAME_LENGTH,
+  MAX_QUESTION_LENGTH,
+  MAX_REPORTS_PER_RUN,
+  MAX_SEARCH_LENGTH,
+  MAX_SECRET_LENGTH,
+  MAX_SKILLS_ADDRESS_LENGTH,
+  MAX_SUMMARY_LENGTH,
+  MAX_TITLE_LENGTH,
+  MAX_TOKEN_DAYS,
+  MAX_TOKEN_NAME_LENGTH,
+  MAX_TOKENS_PER_PERSON,
+  MAX_URL_LENGTH,
+  MAX_VERSIONS_PER_DOCUMENT,
+  MIN_OPTIONS,
+} from "./limits.js";
+export {
+  AUTH_ROUTES,
+  CLAIM_PATH,
+  connectPath,
+  isSignInFailure,
+  loginPath,
+  PROJECT_COLLECTIONS,
+  type ProjectCollection,
+  personTokensPath,
+  projectPath,
+  REST_ROUTES,
+  RETURN_TO_PARAM,
+  restPath,
+  SIGN_IN_FAILURES,
+  SIGN_IN_PARAM,
+  type SignInFailure,
+  signInPath,
+} from "./routes.js";
+export {
+  type RestAnswerInput,
+  type RestArtifact,
+  type RestArtifactInput,
+  type RestBacklink,
+  type RestClaim,
+  type RestClaimInput,
+  type RestConnectInput,
+  type RestConnection,
+  type RestConnectRequest,
+  type RestDecision,
+  type RestDecisionInput,
+  type RestDecisionOption,
+  type RestDecisionPatch,
+  type RestDecisions,
+  type RestDocument,
+  type RestDocumentFile,
+  type RestDocumentInput,
+  type RestDocumentLink,
+  type RestDocumentSummary,
+  type RestDocuments,
+  type RestError,
+  type RestEvent,
+  type RestEventData,
+  type RestEvents,
+  type RestFile,
+  type RestFileInput,
+  type RestMe,
+  type RestMember,
+  type RestMemberInput,
+  type RestMemberPatch,
+  type RestMembers,
+  type RestMePatch,
+  type RestPeople,
+  type RestPerson,
+  type RestPersonPatch,
+  type RestProject,
+  type RestProjectInput,
+  type RestProjectPatch,
+  type RestProjects,
+  type RestProvider,
+  type RestReport,
+  type RestReportInput,
+  type RestRun,
+  type RestRunEndInput,
+  type RestRunInput,
+  type RestRuns,
+  type RestSkill,
+  type RestSkills,
+  type RestTask,
+  type RestTaskInput,
+  type RestTaskLink,
+  type RestTaskPatch,
+  type RestTasks,
+  type RestToken,
+  type RestTokenCreated,
+  type RestTokenInput,
+  type RestTokens,
+  type RestVersion,
+  type RestVersionSummary,
+  type RestVersions,
+  restAnswerInputSchema,
+  restArtifactInputSchema,
+  restArtifactSchema,
+  restBacklinkSchema,
+  restClaimInputSchema,
+  restClaimSchema,
+  restConnectInputSchema,
+  restConnectionSchema,
+  restConnectRequestSchema,
+  restDecisionInputSchema,
+  restDecisionOptionSchema,
+  restDecisionPatchSchema,
+  restDecisionSchema,
+  restDecisionsSchema,
+  restDocumentFileSchema,
+  restDocumentInputSchema,
+  restDocumentLinkSchema,
+  restDocumentSchema,
+  restDocumentSummarySchema,
+  restDocumentsSchema,
+  restErrorSchema,
+  restEventDataSchema,
+  restEventSchema,
+  restEventsSchema,
+  restFileInputSchema,
+  restFileSchema,
+  restMemberInputSchema,
+  restMemberPatchSchema,
+  restMemberSchema,
+  restMembersSchema,
+  restMePatchSchema,
+  restMeSchema,
+  restPeopleSchema,
+  restPersonPatchSchema,
+  restPersonSchema,
+  restProjectInputSchema,
+  restProjectPatchSchema,
+  restProjectSchema,
+  restProjectsSchema,
+  restProviderSchema,
+  restReportInputSchema,
+  restReportSchema,
+  restRunEndInputSchema,
+  restRunInputSchema,
+  restRunSchema,
+  restRunsSchema,
+  restSkillSchema,
+  restSkillsSchema,
+  restTaskInputSchema,
+  restTaskLinkSchema,
+  restTaskPatchSchema,
+  restTaskSchema,
+  restTasksSchema,
+  restTokenCreatedSchema,
+  restTokenInputSchema,
+  restTokenSchema,
+  restTokensSchema,
+  restVersionSchema,
+  restVersionSummarySchema,
+  restVersionsSchema,
+} from "./schemas.js";
+export { hasForbiddenCodePoint } from "./text.js";
+export {
+  ARTIFACT_KINDS,
+  type ArtifactKind,
+  EVENT_KINDS,
+  type EventKind,
+  isProviderKey,
+  LINK_SOURCES,
+  type LinkSource,
+  PERSON_ROLES,
+  type PersonRole,
+  PROJECT_ROLES,
+  PROJECT_VISIBILITIES,
+  PROVIDER_KEYS,
+  type ProjectRole,
+  type ProjectVisibility,
+  type ProviderKey,
+  RUN_ENDINGS,
+  RUN_STATUSES,
+  type RunEnding,
+  type RunStatus,
+  SKILLS_STATUSES,
+  type SkillsStatus,
+  TASK_PRIORITIES,
+  TASK_STATES,
+  type TaskPriority,
+  type TaskState,
+} from "./vocabulary.js";