@chalky/chalky 0.0.0-stage → 0.1.4

package/app/extensions/voice/index.ts

@@ -0,0 +1,37 @@
+// Voice input: speech to text (port of the Python voice plugin). The browser half: a microphone button by the send
+// button (browser.js) and /ui/voice.js, which apps can import too.
+// Settings (environment, like MODEL_*): STT_BASE_URL, STT_MODEL, STT_API_KEY. With STT_BASE_URL set, audio goes to
+// POST {STT_BASE_URL}/audio/transcriptions, OpenAI's endpoint, which most providers speak (OpenAI, Groq, Mistral,
+// vLLM; others through LiteLLM). Without it, voice.js uses the browser's own speech recognition.
+// The key stays here: apps are agent-written code, so they post audio to this server, never to the provider.
+//   GET  /voice-api/config      {"api": true | false}: whether audio can go to the API
+//   POST /voice-api/transcribe  multipart: file (a complete audio file, e.g. chunk.webm), language?, prompt?
+//                               -> {"text"} or {"error"} (with the provider's status)
+import { Readable } from "node:stream";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const host = (globalThis as any).chalky;
+
+export default function (_pi: ExtensionAPI) {
+  const base = (process.env.STT_BASE_URL || "").replace(/\/$/, "");
+  const json = (res: any, status: number, data: object) =>
+    res.writeHead(status, { "content-type": "application/json" }).end(JSON.stringify(data));
+
+  host.routes.set("/voice-api/config", (_req: any, res: any) => json(res, 200, { api: !!base }));
+
+  host.routes.set("/voice-api/transcribe", async (req: any, res: any) => {
+    if (!base) return json(res, 400, { error: "no STT_BASE_URL: use the browser's speech recognition" });
+    try {
+      // the page's form as is, plus the model (Node reads multipart itself: Request.formData)
+      const form = await new Request("http://local", { method: "POST", headers: req.headers,
+        body: Readable.toWeb(req) as any, duplex: "half" } as any).formData();
+      if (!(form.get("file") instanceof Blob)) return json(res, 400, { error: "no audio file" });
+      form.set("model", process.env.STT_MODEL || "whisper-1");
+      const r = await fetch(`${base}/audio/transcriptions`, { method: "POST", body: form,
+        headers: process.env.STT_API_KEY ? { authorization: `Bearer ${process.env.STT_API_KEY}` } : {} });
+      const data: any = await r.json().catch(() => ({}));
+      if (!r.ok) return json(res, 502, { error: `speech to text: ${r.status} ${data.error?.message ?? ""}`.trim() });
+      json(res, 200, { text: data.text ?? "" });
+    } catch (e: any) { json(res, 502, { error: `speech to text: ${e.message}` }); }
+  });
+}

package/app/mcp.json

@@ -0,0 +1,3 @@
+{
+  "mcpServers": {}
+}

package/app/settings.json

@@ -0,0 +1,3 @@
+{
+  "compaction": { "keepRecentTokens": 20000 }
+}

package/app/skills/plugin-map/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: plugin-map
+description: Find your way around your own code (the pi extensions in your code folder, the page among them) without reading whole files. Use before changing yourself, or before planning work for others that will.
+---
+# Getting a map of your own code
+
+Your code folder is the one your prompt names (it holds `extensions/`). Every feature is one extension, and every
+extension is one folder, `extensions/<name>/`, holding all of that feature:
+
+| File          | What it is                                                         |
+|---------------|--------------------------------------------------------------------|
+| `index.ts`    | the extension itself (pi loads it); starts with a header comment    |
+| `guide.md`    | its short prompt section (the part you are reading in your own prompt) |
+| `README.md`   | the whole of what the guide says, read when the guide says          |
+| `browser.js`  | its part of the page (the page extension loads every one it finds)  |
+| `skills/`     | skills only this feature needs (its index.ts gives them to pi)      |
+
+An extension can have other files too (`ui/` has its components, `page/` has `page.html`). The headers are the
+documentation, kept with the code, so read them before the code itself.
+
+## 1. The map: one line per extension
+From your code folder:
+```
+for d in extensions/*/; do printf '%-24s %s\n' "$d" "$(grep -m1 '^//' "$d/index.ts" | sed 's|^// \?||' | cut -c1-140)"; done
+```
+Also there:
+- `extensions/page/`: the page itself (`page.html`), its list of browser parts, and what serves them.
+- `extensions/ui/components/*.js`: UI components, each starting with a comment line on what it is, then its
+  `about` block (props, levers, example; `head -20 <file>`).
+- `skills/<name>/SKILL.md`: skills about you as a whole (this one); a feature's own skills are in its folder.
+- `ui/`: what you built, not code: `surfaces.json` (the surfaces' design) and `apps/<name>/`.
+- The host, `server.ts` one folder up: sessions, the web server, `globalThis.chalky`. Read its header; don't edit it.
+
+## 2. The headers of the extensions involved
+```
+awk '/^import /{exit} 1' extensions/swarm/index.ts     # everything above the imports
+```
+Read only the headers of the extensions your work touches. All of them at once is over 13,000 characters.
+
+## 3. Then only the code you will change
+Use `grep -n` to find the function, then `sed -n 'START,ENDp'` for that part. A whole file can be long
+(swarm's index.ts is over 16,000 characters). If you are planning work for other agents, the headers are usually
+enough: let each agent read the code it owns.
+
+## Keep the headers true
+When you change what an extension provides (a tool, a route, a page message, an event, a host service), update
+its header in the same change. Other agents, and you after a reload, rely on it. A new extension is a new folder
+with an `index.ts` whose header starts with a one-line summary: that line is its entry in the map. After editing,
+call the reload tool.

package/app/skills/write-skill/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: write-skill
+description: How to write or improve a skill (SKILL.md format, folder layout, a good description). Use when you want to save a method you worked out so you and other agents can reuse it, or when a skill is listed as broken.
+---
+# Writing a skill
+
+## When a skill is worth it
+- You worked out a method that wasn't obvious, and the task will come up again (here or in later runs).
+- You hit a pitfall that cost time. Save the fix, not the story.
+- Not for facts about the current project: those belong in the project's own files (e.g. CONTRACTS.md).
+- One skill per kind of task. If one already covers it, improve that one instead of adding another.
+
+## Layout
+```
+skills/<name>/    in your code folder (the one your prompt names, with extensions/ in it)
+  SKILL.md        required: front matter + instructions
+  scripts/        optional: code to run (node or bash; python only if it is installed)
+  references/     optional: longer docs, read only when needed
+  assets/         optional: templates, data files
+```
+A skill that only one feature needs goes in that extension's folder instead, `extensions/<name>/skills/<skill>/`
+(as `extensions/ui/skills/`), and its `index.ts` gives the folder to pi:
+`pi.on("resources_discover", () => ({ skillPaths: [path.join(import.meta.dirname, "skills")] }))`.
+
+## SKILL.md
+```markdown
+---
+name: csv-report
+description: Turns a CSV file into a summary report with totals per column. Use when the user gives a CSV and asks for a summary, report or totals.
+---
+# CSV report
+1. Run `node scripts/report.mjs <file.csv>` (paths are relative to this skill's folder) to get the totals.
+...
+```
+- `name`: exactly the folder's name. Lowercase letters, digits and single hyphens; at most 64 characters.
+- `description`: at most 1024 characters. Say what it does AND when to use it, with the words a matching
+  task would contain. Agents decide whether to load the skill from this line alone, so it matters most.
+
+## Writing the body
+- Write steps in the imperative ("Run …", "Check …"), with a short example of input and output.
+- Explain why a step matters instead of shouting MUST: an agent that understands the reason handles
+  cases you didn't foresee. Keep it general, not tied to the one case you just solved.
+- Work that must come out the same every time (parsing, checks, setup) goes in a script, not in prose.
+  Run the script once before saving it.
+- Keep SKILL.md under ~500 lines. Move long material to references/ and say when to read each file.
+  A reference over ~300 lines gets a table of contents at the top.
+- If the skill covers variants (e.g. several frameworks), keep the shared workflow in SKILL.md and one
+  reference per variant (references/react.md, references/vue.md), so only the relevant one is read.
+- Refer to files by paths relative to the skill folder.
+- No surprises: a skill does what its description says. Never put secrets (keys, passwords) in one.
+
+## After writing
+- Call the reload tool: your skill list loads again when your turn ends, and the new skill shows in your prompt
+  (name, description and path; you read SKILL.md with read). If it doesn't show, its front matter is wrong.
+- Read it once as a newcomer would: is anything only clear because you just did the work?
+- Skills are shared, but another agent only sees a new skill after it reloads (tell it to call reload).
+  Tell the user what you added.

package/bin/chalky.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// chalky: starts Chalky from the installed package. Its home (app/, state/, workspace/) is CHALKY_HOME, else
+// ~/.chalky; the first run copies the package's app/ there. Node won't run TypeScript under node_modules
+// (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), so server.ts loads through jiti, as pi loads extensions.
+//   MODEL_BASE_URL=... MODEL_API_KEY=... [MODEL_NAME=...] chalky
+import os from "node:os";
+import path from "node:path";
+import { createJiti } from "jiti";
+
+process.env.CHALKY_HOME ??= path.join(os.homedir(), ".chalky");
+await createJiti(import.meta.url).import(path.join(import.meta.dirname, "../server.ts"));

package/node_modules/xlsx/CHANGELOG.md

@@ -0,0 +1,361 @@
+# CHANGELOG
+
+This log is intended to keep track of backwards-incompatible changes, including
+but not limited to API changes and file location changes.  Minor behavioral
+changes may not be included if they are not expected to break existing code.
+
+## v0.20.3
+
+* Correct parsing of NUMBERS and ODS merge cells (h/t @s-ashwin)
+* More precise treatment of infinite and NaN values
+* XLML Streaming Write
+* Parse `Int8Array` objects (for compatibility with JS engines in Java)
+* CSV Export only quote leading ID (h/t @lako12)
+
+## v0.20.2
+
+* Reworked parsing methods to avoid slow regexes (CVE-2024-22363)
+* HTML properly encode data-v attribute
+* SYLK read and write error cells
+
+## v0.20.1
+
+* `init` use packaged test files to work around GitHub breaking changes
+* SSF date code rounding to 15 decimal digits (h/t @davidtamaki)
+* `sheet_to_json` force UTC interpretation for formatted strings (h/t @Blanay)
+* QPW extract result of string formula
+* XLSX parse non-compliant merge cell expressions
+* NUMBERS correctly handle rows omitted from official exports
+* DBF parse empty logical field (h/t @Roman91)
+* `dense` option added to types
+* package.json add mini and core scripts to export map (h/t @stof)
+
+## v0.20.0
+
+* Use UTC interpretation of Date objects for date cells (potentially breaking)
+* API functions support UTC and local time value interpretations
+* Export `NaN` values to `#NUM!` and infinite values to `#DIV/0!`
+
+## v0.19.3
+
+* XLSX Ensure comment address is valid (h/t @slonser)
+* Enforce Excel worksheet name restrictions
+* Fixed "Prototype Pollution" vulnerability (CVE-2023-30533)
+
+## v0.19.2
+
+* XLSX proper decoding of hyperlinks (h/t @tw-yaxu)
+* XLSX ignore unexpected attributes in rich text (h/t @colin4)
+* `sheet_to_json` type fix (h/t @chsdwn)
+
+## v0.19.1
+
+* Fixed types issue in strict mode (h/t @younes-io)
+* Numbers 12.2 parsing skip ActivityStream.iwa
+
+## v0.19.0
+
+* XLSX export hyperlinks compatible with google sheets (h/t Evan Bovie)
+* NUMBERS export multiple sheets, full worksheet range
+* formalized `dense` mode
+
+## v0.18.12
+
+* `package.json` added types in `exports` structure
+* uncapped NUMBERS single-sheet single-table export
+* DBF export records using supported codepages
+
+## v0.18.11
+
+* Base64 input ignore data URI wrapper
+* Parse ZIP files that use ZIP64 extended information field
+* More precise handling of time-only values
+* Threaded Comment fallback text for older Excel
+
+## v0.18.10
+
+* `exports` field in package.json to satiate ViteJS and newer tooling
+* JSC (Safari / Bun) perf, see <https://bugs.webkit.org/show_bug.cgi?id=243148>
+* workbook `bookType` property to denote the origin format when parsed from file
+* XLSX force export of stub cells with number formats when `sheetStubs` is set
+
+## v0.18.9
+
+* XLSX / ODS write defined names
+* sync defined names to AutoFilter setting on export
+* 1904 date system setting properly roundtripped
+* ODS read/write number formats
+
+## v0.18.8
+
+* Plaintext parsing of dateless meridien time values (`1:23:45 PM`)
+* Legacy format (SYLK / WK# / Multiplan) minutiae
+
+## v0.18.7
+
+* Normalized handling of `\r` and `\n` newline characters
+
+## v0.18.6
+
+* Removed all npm dependencies
+* Auto-correct bad Google Sheets format `d.m`
+* NUMBERS write merge cells, cells up to column "ALL"
+
+## v0.18.5
+
+* Enabled `sideEffects: false` in package.json
+* Basic NUMBERS write support
+
+## v0.18.4
+
+* CSV output omits trailing record separator
+* Properly terminate NodeJS Streams
+* DBF preserve column types on import and use when applicable on export
+
+## v0.18.3
+
+* Removed references to `require` and `process` in browser builds
+
+## v0.18.2
+
+* Hotfix for unicode processing of XLSX exports
+
+## v0.18.1
+
+* Removed Node ESM build script and folded into standard ESM build
+* Removed undocumented aliases including `make_formulae` and `get_formulae`
+
+## v0.18.0
+
+* Browser scripts only expose `XLSX` variable
+* Module no longer ships with `dist/jszip.js` browser script
+
+## v0.17.4
+
+* CLI script moved to `xlsx-cli` package
+
+## v0.17.3
+
+* `window.XLSX` explicit assignment to satiate LWC
+* CSV Proper formatting of errors
+* HTML emit data-\* attributes
+
+## v0.17.2
+
+* Browser and Node optional ESM support
+* DSV correct handling of bare quotes (h/t @bgamrat)
+
+## v0.17.1
+
+* `XLSB` writer uses short cell form when viable
+
+## 0.17.0:
+
+* mini build includes ODS parse/write support
+* DBF explicitly cap worksheet to 1<<20 rows
+* XLS throw errors on truncated records
+
+## v0.16.2
+
+* Disabled `PRN` parsing by default (better support for CSV without delimeters)
+
+## v0.16.1
+
+* skip empty custom property tags if data is absent (fixes DocSecurity issue)
+* HTML output add raw value, type, number format
+* DOM parse look for `v` / `t` / `z` attributes when determining value
+* double quotes in properties escaped using `_x0022_`
+* changed AMD structure for NetSuite and other RequireJS implementations
+- `encode_cell` and `decode_cell` do not rely on `encode_col` / `decode_col`
+
+## v0.16.0
+
+* Date handling changed
+* XLML certain tag tests are now case insensitive
+* Fixed potentially vulnerable regular expressions
+
+## v0.15.6
+
+* CFB prevent infinite loop
+* ODS empty cells marked as stub (type "z")
+* `cellStyles` option implies `sheetStubs`
+
+## v0.15.5
+
+* `sheets` parse option to specify which sheets to parse
+
+## v0.15.4
+
+* AOA utilities properly preserve number formats
+* Number formats captured in stub cells
+
+## v0.15.3
+
+* Properties and Custom Properties properly XML-encoded
+
+## v0.15.2
+
+- `sheet_get_cell` utility function
+- `sheet_to_json` explicitly support `null` as alias for default behavior
+- `encode_col` throw on negative column index
+- HTML properly handle whitespace around tags in a run
+- HTML use `id` option on write
+- Files starting with `0x09` followed by a display character are now TSV files
+- XLS parse references col/row indices mod by the correct number for BIFF ver
+- XLSX comments moved to avoid overlapping cell
+- XLSB outline level
+- AutoFilter update `_FilterDatabase` defined name on write
+- XLML skip CDATA blocks
+
+## v0.15.1 (2019-08-14)
+
+* XLSX ignore XML artifacts
+* HTML capture and persist merges
+
+## v0.15.0
+
+* `dist/xlsx.mini.min.js` mini build with XLSX read/write and some utilities
+* Removed legacy conversion utility functions
+
+## v0.14.5
+
+* XLS PtgNameX lookup
+* XLS always create stub cells for blank cells with comments
+
+
+## v0.14.4
+
+* Better treatment of `skipHidden` in CSV output
+* Ignore CLSID in XLS
+* SYLK 7-bit character encoding
+* SYLK and DBF codepage support
+
+## v0.14.3
+
+* Proper shifting of addresses in Shared Formulae
+
+## v0.14.2
+
+* Proper XML encoding of comments
+
+## v0.14.1
+
+* raw cell objects can be passed to `sheet_add_aoa`
+* `_FilterDatabase` fix for AutoFilter-related crashes
+* `stream.to_json` doesn't end up accidentally scanning to max row
+
+## 0.14.0 (2018-09-06)
+
+* `sheet_to_json` default flipped to `raw: true`
+
+## 0.13.5 (2018-08-25)
+
+* HTML output generates `<br/>` instead of encoded newline character
+
+## 0.13.2 (2018-07-08)
+
+* Buffer.from shim replaced, will not be defined in node `<=0.12`
+
+## 0.13.0 (2018-06-01)
+
+* Library reshaped to support AMD out of the box
+
+## 0.12.11 (2018-04-27)
+
+* XLS/XLSX/XLSB range truncation (errors in `WTF` mode)
+
+## 0.12.4 (2018-03-04)
+
+* `JSZip` renamed to `JSZipSync`
+
+## 0.12.0 (2018-02-08)
+
+* Extendscript target script in NPM package 
+
+## 0.11.19 (2018-02-03)
+
+* Error on empty workbook
+
+## 0.11.16 (2017-12-30)
+
+* XLS ANSI/CP separation
+* 'array' write type and ArrayBuffer processing
+
+## 0.11.6 (2017-10-16)
+
+* Semicolon-delimited files are detected
+
+## 0.11.5 (2017-09-30)
+
+* Bower main script shifted to full version
+* 'binary' / 'string' encoding
+
+## 0.11.3 (2017-08-19)
+
+* XLS cell ixfe/XF removed
+
+## 0.11.0 (2017-07-31)
+
+* Strip `require` statements from minified version
+* minifier mangler enabled
+
+## 0.10.9 (2017-07-28)
+
+* XLML/HTML resolution logic looks further into the data stream to decide type
+* Errors thrown on suspected RTF files
+
+## 0.10.5 (2017-06-09)
+
+* HTML Table output header/footer should not include `<table>` tag
+
+## 0.10.2 (2017-05-16)
+
+* Dates are converted to numbers by default (set `cellDates:true` to emit Dates)
+* Module does not export CFB
+
+## 0.9.10 (2017-04-08)
+
+* `--perf` renamed to `--read-only`
+
+## 0.9.9 (2017-04-03)
+
+* default output format changed to XLSB
+* comment text line endings are now normalized
+* errors thrown on write when worksheets have invalid names
+
+## 0.9.7 (2017-03-28)
+
+* XLS legacy `!range` field removed
+* Hyperlink tooltip is stored in the `Tooltip` field
+
+## 0.9.6 (2017-03-25)
+
+* `sheet_to_json` now passes `null` values when `raw` is set to `true`
+* `sheet_to_json` treats `null` stub cells as values in conjunction with `raw`
+
+## 0.9.5 (2017-03-22)
+
+* `cellDates` affects parsing in non-XLSX formats
+
+## 0.9.3 (2017-03-15)
+
+* XLML property names are more closely mapped to the XLSX equivalent
+* Stub cells are now cell type `z`
+
+## 0.9.2 (2017-03-13)
+
+* Removed stale TypeScript definition files.  Flowtype comments are used in the
+  `xlsx.flow.js` source and stripped to produce `xlsx.js`.
+* sed usage reworked to support GNU sed in-place form.  BSD sed seems to work,
+  but the build script has not been tested on other sed variants:
+
+```bash
+$ sed -i.ext  [...] # GNU
+$ sed -i .ext [...] # bsd
+```
+
+## 0.9.0 (2017-03-09)
+
+* Removed ods.js source.  The xlsx.js source absorbed the ODS logic and exposes
+  the ODS variable, so projects should remove references to ods.js
+