@skillcdn/console 0.1.7 → 0.1.9

package/skills/deploying-a-console/references/sizing.md

@@ -0,0 +1,90 @@
+# Sizing and cost: three sizes, and what each costs
+
+How the organization's size becomes a size of the deployment, what each size is made of, how its monthly cost is estimated before anything is made, and what changes when the organization grows. Every price here is a snapshot that illustrates the shape, marked with the month it was read; the run reads today's prices where it can, shows those, and says which lines are still the snapshot.
+
+## The sizes
+
+The question is how many people will use the console within a year; an answer stands for the run and is written in the record. Growing later is a change of numbers (below).
+
+| Size | For | The `api` service | The `worker` | The database | What else |
+|---|---|---|---|---|---|
+| `small` | Up to 10 people | One task, 0.25 vCPU, 0.5 GB, carrying the worker's work (`WORKER_IN_PROCESS=true`) | In the `api` task | One instance, the smallest class with 1 GB of memory (`db.t4g.micro`), 20 GB growing to 100, one zone | A bucket, the parameter store, one public address for the task's egress |
+| `medium` | Up to 30 people | One task, 0.5 vCPU, 1 GB, carrying the worker's work | In the `api` task | One instance with 2 GB (`db.t4g.small`), 20 GB growing to 100, one zone | The same |
+| `large` | Up to 100 people | Two tasks, 0.5 vCPU, 1 GB each | A service of its own, one task, 0.25 vCPU, 0.5 GB | One instance with 4 GB (`db.t4g.medium`), 20 GB growing to 200; in two zones when the organization wants the database to survive a zone | The same, with three public addresses |
+
+The board is a light load: a page, a feed held open per browser tab with a heartbeat every 25 seconds, a command now and then from each agent. What grows with people is the number of open feeds (memory and connections) and the database's working set, not the CPU. These sizes leave room; the delivery says how to read the gauges (below) and the record says which size was chosen.
+
+## What is billed
+
+| Item | How it is billed | Illustrative price, N. Virginia (`us-east-1`), read 2026-10 |
+|---|---|---|
+| Fargate tasks | Per vCPU-hour and per GB-hour of each task, per second, a minute at least; x86 by default, ARM about a fifth cheaper when the image is built for it | x86 $0.04048 per vCPU-hour, $0.004445 per GB-hour; ARM $0.03238 and $0.00356 |
+| Public IPv4 address, one per task | Per hour | $0.005 per hour, about $3.65 a month |
+| RDS PostgreSQL instance | Per hour by class; two zones doubles it | `db.t4g.micro` $0.016 per hour, `db.t4g.small` $0.032 per hour, `db.t4g.medium` about twice the small |
+| RDS storage, `gp3` | Per GB-month of what is allocated; backups up to the instance's size are free | $0.115 per GB-month |
+| S3 | Per GB-month and per request; a board's files are small | $0.023 per GB-month |
+| ECR | Per GB-month of images kept | $0.10 per GB-month |
+| CloudWatch Logs | Per GB ingested and per GB-month kept, 30 days here | $0.50 per GB ingested, $0.03 per GB-month |
+| SSM Parameter Store | Standard parameters free; the certificate bundle is an advanced parameter | $0.05 per advanced parameter a month |
+| Cloudflare | The Free plan: DNS, the proxy, the tunnel, one rate limiting rule, certificates | $0 |
+| A domain | Per year, at cost through the Registrar | About $10 a year for a `.com` |
+| GitHub Actions | Minutes of the deployment repository's builds; a build takes about ten | Within the minutes a plan includes |
+
+Other regions are dearer by a tenth to a third for the same items (Tokyo's ARM task rates were about a quarter above N. Virginia's, read 2026-10); Seoul's rates are read from the price list in the run. A new AWS account made after 2025-07-15 starts with credits ($100 at sign-up, up to $200 with the first activities), which the paid plan spends on these bills over the first months; the free plan ends after six months and is not for a console that stays.
+
+## The estimate, size by size
+
+Illustrative, from the prices above, x86 tasks, one zone, 730 hours a month, read 2026-10. The run recomputes each line with the prices of the day and the region, and shows the chosen size with the next one beside it.
+
+| Size | Tasks | Addresses | Database | Storage, logs, images | About |
+|---|---|---|---|---|---|
+| `small` | $9 | $4 | $12 | $3 | $28 a month |
+| `medium` | $18 | $4 | $23 | $4 | $49 a month |
+| `large` | $45 | $11 | $47 (one zone) or $95 (two) | $6 | $109 a month, $157 in two zones |
+
+A domain is on top, per year. Cloudflare costs nothing on the Free plan.
+
+## Reading today's prices
+
+The two lines that matter, the tasks and the database, come from the Price List API, which answers from `us-east-1` whatever the region priced (the deployer's policy allows `pricing:GetProducts`); the small lines (the address, storage, logs, images) from the pricing pages, or the snapshot with the region's premium stated. The database's instance, per hour:
+
+```sh
+aws pricing get-products --region us-east-1 --service-code AmazonRDS \
+  --filters Type=TERM_MATCH,Field=instanceType,Value=<db.t4g.micro | db.t4g.small | db.t4g.medium> \
+            Type=TERM_MATCH,Field=databaseEngine,Value=PostgreSQL \
+            Type=TERM_MATCH,Field=deploymentOption,Value=<Single-AZ | Multi-AZ> \
+            Type=TERM_MATCH,Field=regionCode,Value=<region> \
+  --query 'PriceList[0]' --output text | jq -r '.terms.OnDemand[] | .priceDimensions[] | .pricePerUnit.USD'
+```
+
+The tasks, per vCPU-hour and per GB-hour, by the usage type of the region (`APN2` for Seoul, `APN1` for Tokyo, `EUC1` for Frankfurt, `EUW1` for Ireland, `USE2` for Ohio, no prefix for N. Virginia; `ARM-` before `vCPU` and `GB` for ARM tasks):
+
+```sh
+for usage in "<prefix>-Fargate-vCPU-Hours:perCPU" "<prefix>-Fargate-GB-Hours"; do
+  aws pricing get-products --region us-east-1 --service-code AmazonECS \
+    --filters Type=TERM_MATCH,Field=usagetype,Value="$usage" Type=TERM_MATCH,Field=regionCode,Value=<region> \
+    --query 'PriceList[0]' --output text | jq -r '.terms.OnDemand[] | .priceDimensions[] | .pricePerUnit.USD'
+done
+```
+
+The pages, each with the region selected, for the rest: the public IPv4 charge on the EC2 pricing page (`aws.amazon.com/ec2/pricing/on-demand`, "IPv4 address"), S3 (`aws.amazon.com/s3/pricing`), ECR, CloudWatch; or the AWS Pricing Calculator. A lookup that fails is said so in the plan, and that line is the snapshot with the premium of "What is billed" applied, named as an estimate. State in the plan where each number came from and the month.
+
+## The estimate message
+
+Part of the plan, in plain words, one line per item, the chosen size first:
+
+> For <n> people I would set it up as **<size>**: <what it is made of, in words>. That is about **<total> a month** in <region> (<tasks>, <database>, <addresses>, <the rest>; <which lines are today's prices and which the snapshot>)<, plus the domain at <price> a year when one is bought>. The next size up, **<size>**, would be about <total> a month and is a change of numbers later, not a new deployment. A budget alert at <total × 1.5> will email <address> when the month's bill runs past it, or is forecast to.
+
+## Options the plan offers
+
+- **The database as serverless capacity.** Aurora Serverless v2 for PostgreSQL scales its capacity with load, down to nothing when idle (0 ACU with automatic pause, since 2024-11). The console holds a listening connection open and sweeps every fifteen minutes, so it never idles and the database never pauses: the floor is 0.5 ACU, about $44 a month at $0.12 per ACU-hour (read 2026-10), more than the `small` and `medium` instances. Offer it when the organization wants capacity that follows load without resizing, and say the floor.
+- **The bucket on Cloudflare R2** instead of S3: the same S3 API, `S3_ENDPOINT=https://<account id>.r2.cloudflarestorage.com`, `S3_REGION=auto`, path style; no egress charges. Its keys are made in the Cloudflare dashboard (R2, Manage API tokens, Object Read & Write on the one bucket), saved in the secrets file as `S3_ACCESS_KEY_ID` and `S3_SECRET_ACCESS_KEY`, stored as parameters and carried by the `api` task as secrets, with no `S3_CREDENTIALS` line: the task's role cannot reach R2. Offer it when the organization keeps its files at Cloudflare already; S3 stays the default because the task's own role reaches it with no key to keep, and the budget and the audit are then in one account.
+- **A load balancer instead of the tunnel.** ECS Express Mode creates an Application Load Balancer with HTTPS on an AWS domain in one command, at about $16 to $23 a month for the balancer (read 2026-10); the custom domain is a manual step on the balancer, and Cloudflare then proxies to it. Offer it only when the organization does not want its traffic through the tunnel; the tunnel is the default because it costs nothing, exposes nothing, and brings the client's address to the console cleanly.
+- **ARM tasks** when the organization has ARM runners for its builds (building for ARM on an x86 runner takes many times longer): a fifth off the task line.
+
+## Growing
+
+- **More people:** change the task sizes and counts in `deploy/api.task.json` and `deploy/worker.task.json` of the deployment repository and push; the services roll. At `large`, the `worker` becomes a service of its own and `WORKER_IN_PROCESS` is dropped from the `api` task; `deploy.yml` deploys both.
+- **A bigger database:** `aws rds modify-db-instance --db-instance-identifier <name> --db-instance-class <class> --apply-immediately` (a few minutes of unavailability; do it when nobody works) and, for two zones, `--multi-az`. Storage grows on its own up to the maximum set.
+- **Reading the gauges:** the ECS service's CPU and memory in CloudWatch (`AWS/ECS`, by cluster and service), the database's `FreeableMemory` and `DatabaseConnections` (`AWS/RDS`). Memory above 70% or connections near the instance's limit (87 on a `t4g.micro`) says the next size is due.
+- **Fewer people, or a trial that ended:** the opposite; or `aws ecs update-service --desired-count 0` for both services and `aws rds stop-db-instance` (seven days at most, then it starts itself) to pause the deployment at the cost of storage alone.

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,100 @@
+// 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 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|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 "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

@@ -1,21 +1,29 @@
 ---
 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."
+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.0"
+  version: "1.1"
 skillcdn:
   translations:
     ko:
       title: 콘솔 보드에서 일하기
-      description: "SkillCDN 콘솔의 보드에 있는 작업을 console 명령으로 수행합니다. 명령에 로그인한 사람의 자격으로, 작업을 읽고 맡고, 진행의 이정표마다 보고하고, 사람이 정해야 할 일은 보드에 물어 답을 기다리고, 만든 것을 링크나 파일로 제출하고, 다음 에이전트에게 필요한 것을 프로젝트 페이지에 적고, 마칩니다. 에이전트에게 콘솔의 작업을 맡거나 끝내라고, 또는 보고·질문·제출·페이지 쓰기를 하라고 할 때 쓰세요. 콘솔이나 API 클라이언트를 만들 때는 building-a-console을 쓰세요."
+      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 |