@qvac/skills 0.0.0 → 0.1.1

package/LICENSE.md

@@ -0,0 +1,198 @@
+# License
+
+This project is licensed under the Apache License, Version 2.0.
+See below for the full license text.
+
+## Apache License
+
+_Version 2.0, January 2004_  
+_&lt;<http://www.apache.org/licenses/>&gt;_
+
+### Terms and Conditions for use, reproduction, and distribution
+
+#### 1. Definitions
+
+“License” shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+“Licensor” shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+“Legal Entity” shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, “control” means **(i)** the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or **(ii)** ownership of fifty percent (50%) or more of the
+outstanding shares, or **(iii)** beneficial ownership of such entity.
+
+“You” (or “Your”) shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+“Source” form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+“Object” form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+“Work” shall mean the work of authorship, whether in Source or Object form, made
+available under the License, as indicated by a copyright notice that is included
+in or attached to the work (an example is provided in the Appendix below).
+
+“Derivative Works” shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+“Contribution” shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work
+by the copyright owner or by an individual or Legal Entity authorized to submit
+on behalf of the copyright owner. For the purposes of this definition,
+“submitted” means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems, and
+issue tracking systems that are managed by, or on behalf of, the Licensor for
+the purpose of discussing and improving the Work, but excluding communication
+that is conspicuously marked or otherwise designated in writing by the copyright
+owner as “Not a Contribution.”
+
+“Contributor” shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+#### 2. Grant of Copyright License
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the Work and such
+Derivative Works in Source or Object form.
+
+#### 3. Grant of Patent License
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable (except as stated in this section) patent license to make, have
+made, use, offer to sell, sell, import, and otherwise transfer the Work, where
+such license applies only to those patent claims licensable by such Contributor
+that are necessarily infringed by their Contribution(s) alone or by combination
+of their Contribution(s) with the Work to which such Contribution(s) was
+submitted. If You institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work or a
+Contribution incorporated within the Work constitutes direct or contributory
+patent infringement, then any patent licenses granted to You under this License
+for that Work shall terminate as of the date such litigation is filed.
+
+#### 4. Redistribution
+
+You may reproduce and distribute copies of the Work or Derivative Works thereof
+in any medium, with or without modifications, and in Source or Object form,
+provided that You meet the following conditions:
+
+- **(a)** You must give any other recipients of the Work or Derivative Works a copy of
+  this License; and
+- **(b)** You must cause any modified files to carry prominent notices stating that You
+  changed the files; and
+- **(c)** You must retain, in the Source form of any Derivative Works that You distribute,
+  all copyright, patent, trademark, and attribution notices from the Source form
+  of the Work, excluding those notices that do not pertain to any part of the
+  Derivative Works; and
+- **(d)** If the Work includes a “NOTICE” text file as part of its distribution, then any
+  Derivative Works that You distribute must include a readable copy of the
+  attribution notices contained within such NOTICE file, excluding those notices
+  that do not pertain to any part of the Derivative Works, in at least one of the
+  following places: within a NOTICE text file distributed as part of the
+  Derivative Works; within the Source form or documentation, if provided along
+  with the Derivative Works; or, within a display generated by the Derivative
+  Works, if and wherever such third-party notices normally appear. The contents of
+  the NOTICE file are for informational purposes only and do not modify the
+  License. You may add Your own attribution notices within Derivative Works that
+  You distribute, alongside or as an addendum to the NOTICE text from the Work,
+  provided that such additional attribution notices cannot be construed as
+  modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise complies
+with the conditions stated in this License.
+
+#### 5. Submission of Contributions
+
+Unless You explicitly state otherwise, any Contribution intentionally submitted
+for inclusion in the Work by You to the Licensor shall be under the terms and
+conditions of this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify the terms of
+any separate license agreement you may have executed with Licensor regarding
+such Contributions.
+
+#### 6. Trademarks
+
+This License does not grant permission to use the trade names, trademarks,
+service marks, or product names of the Licensor, except as required for
+reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+#### 7. Disclaimer of Warranty
+
+Unless required by applicable law or agreed to in writing, Licensor provides the
+Work (and each Contributor provides its Contributions) on an “AS IS” BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,
+including, without limitation, any warranties or conditions of TITLE,
+NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are
+solely responsible for determining the appropriateness of using or
+redistributing the Work and assume any risks associated with Your exercise of
+permissions under this License.
+
+#### 8. Limitation of Liability
+
+In no event and under no legal theory, whether in tort (including negligence),
+contract, or otherwise, unless required by applicable law (such as deliberate
+and grossly negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special, incidental,
+or consequential damages of any character arising as a result of this License or
+out of the use or inability to use the Work (including but not limited to
+damages for loss of goodwill, work stoppage, computer failure or malfunction, or
+any and all other commercial damages or losses), even if such Contributor has
+been advised of the possibility of such damages.
+
+#### 9. Accepting Warranty or Additional Liability
+
+While redistributing the Work or Derivative Works thereof, You may choose to
+offer, and charge a fee for, acceptance of support, warranty, indemnity, or
+other liability obligations and/or rights consistent with this License. However,
+in accepting such obligations, You may act only on Your own behalf and on Your
+sole responsibility, not on behalf of any other Contributor, and only if You
+agree to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.
+
+_END OF TERMS AND CONDITIONS_
+
+### APPENDIX: How to apply the Apache License to your work
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets `[]` replaced with your own
+identifying information. (Don't include the brackets!) The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on
+the same “printed page” as the copyright notice for easier identification within
+third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,40 @@
+# @qvac/skills
+
+Skills for QV.AC.
+
+A skill is a directory under `skills/` with a `SKILL.md` in it, plus whatever
+else it needs alongside — reference notes, scripts, a schema. The `SKILL.md`
+front matter is what the harness reads to build its catalog.
+
+The package ships the tree itself and a bundled copy of it, so consumers that
+can't read a filesystem still get the same bytes.
+
+## Entry points
+
+| Import                  | Contents                                 | Needs a filesystem |
+| ----------------------- | ---------------------------------------- | ------------------ |
+| `@qvac/skills`          | `skillsDir`, `skillsUrl`, `SKILLS_HASH`  | yes                |
+| `@qvac/skills/bundled`  | `SKILLS` (path → content), `SKILLS_HASH` | no                 |
+| `@qvac/skills/hash`     | `SKILLS_HASH` alone                      | no                 |
+| `@qvac/skills/skills/*` | a single file by path                    | no                 |
+
+All of them work on Node and Bare. `skillsDir` only points at anything real
+where the package was installed to disk, though — a Bare worklet ships no
+`node_modules`, so it imports `./bundled` and writes the tree out itself.
+
+`SKILLS_HASH` is a sha256 over the sorted `path\0content\0` stream, truncated
+to 16 hex chars. Consumers key a materialized directory on it, so it has to
+match `hashBundledSkills` in the harness byte for byte.
+
+## Development
+
+```sh
+npm test     # node + bare
+npm run lint
+```
+
+`bundled.js` and `hash.js` are generated from `skills/` by `scripts/build.mjs`
+
+## License
+
+Apache-2.0

package/index.d.ts

@@ -0,0 +1,4 @@
+export { SKILLS_HASH } from './hash.js'
+
+export declare const skillsUrl: URL
+export declare const skillsDir: string

package/index.js

@@ -0,0 +1,9 @@
+// Resolves the on-disk tree, for consumers that can read node_modules —
+// desktop main, build steps, tests. A Bare worklet has no such tree on disk,
+// so it imports './bundled' and materializes one instead.
+import { fileURLToPath } from 'url'
+
+export { SKILLS_HASH } from './hash.js'
+
+export const skillsUrl = new URL('./skills/', import.meta.url)
+export const skillsDir = fileURLToPath(new URL('./skills', import.meta.url))

package/package.json

@@ -1 +1,87 @@
-{"name":"@qvac/skills","version":"0.0.0"}
+{
+  "name": "@qvac/skills",
+  "version": "0.1.1",
+  "description": "Skills for the QV.AC app — the SKILL.md tree plus a content-addressed bundle of it.",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    "./package": "./package.json",
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./bundled": {
+      "types": "./bundled.d.ts",
+      "default": "./bundled.js"
+    },
+    "./hash": {
+      "types": "./hash.d.ts",
+      "default": "./hash.js"
+    },
+    "./skills/*": "./skills/*"
+  },
+  "files": [
+    "package.json",
+    "skills",
+    "index.js",
+    "index.d.ts",
+    "bundled.js",
+    "bundled.d.ts",
+    "hash.js",
+    "hash.d.ts"
+  ],
+  "imports": {
+    "fs": {
+      "bare": "bare-fs",
+      "default": "fs"
+    },
+    "path": {
+      "bare": "bare-path",
+      "default": "path"
+    },
+    "crypto": {
+      "bare": "bare-crypto",
+      "default": "crypto"
+    },
+    "url": {
+      "bare": "bare-url",
+      "default": "url"
+    }
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "npm run build",
+    "pretest": "npm run build",
+    "test": "npm run test:node && npm run test:bare",
+    "test:node": "brittle-node test/all.mjs",
+    "test:bare": "brittle-bare test/all.mjs",
+    "test:generate": "brittle-make-test test/all.mjs test/*.js",
+    "format": "prettier . --write",
+    "lint": "prettier . --check && lunte"
+  },
+  "dependencies": {
+    "bare-url": "^2.4.5"
+  },
+  "devDependencies": {
+    "bare-crypto": "^1.15.3",
+    "bare-fs": "^4.7.2",
+    "bare-path": "^3.0.1",
+    "brittle": "^4.1.0",
+    "lunte": "^1.8.4",
+    "prettier": "^3.9.6",
+    "prettier-config-holepunch": "^2.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tetherto/qvac-skills.git"
+  },
+  "author": "Tether Inc",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/tetherto/qvac-skills/issues"
+  },
+  "homepage": "https://github.com/tetherto/qvac-skills",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/apple-notes/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: apple-notes
+description: Read, search, create, edit, append to, and delete notes in the macOS Notes app through bundled AppleScript operations.
+tools: [exec(osascript)]
+platform: [darwin]
+metadata:
+  {
+    'openclaw':
+      {
+        'requires': { 'bins': ['osascript'] },
+        'setup':
+          {
+            'summary': 'Apple Notes works through macOS automation (osascript), which ships with macOS — nothing to install. The first command triggers a one-time permission prompt to let this app control Notes.',
+            'routes':
+              [
+                {
+                  'kind': 'instructions',
+                  'label': 'Allow Notes automation',
+                  'description': "macOS asks once for permission to control Notes. Commands fail until it's granted.",
+                  'steps':
+                    [
+                      'Use the skill once — macOS shows a permission prompt to allow control of Notes.',
+                      'Click Allow.',
+                      'If it was denied, enable it under System Settings → Privacy & Security → Automation.'
+                    ]
+                }
+              ]
+          }
+      }
+  }
+---
+
+# Apple Notes (osascript)
+
+Drive the macOS Notes app through the bundled AppleScript operations, one per
+`exec` call: `osascript {{SKILL_DIR}}/<file>.applescript <args...>`.
+`{{SKILL_DIR}}` resolves to this skill's absolute directory. Never use
+`osascript -e` or any other AppleScript file: the exec grant permits only the
+bundled Notes operations.
+
+## Load the Recipe File First
+
+This file carries no commands. The working recipes live in two reference files —
+load the one for the job with the `skill` tool BEFORE calling `exec`, then copy
+its command and change only the arguments:
+
+Each load is a real `skill` tool call — printing the call as JSON or text in
+your reply loads nothing.
+
+- **Finding or reading notes** — "list my notes", "what notes do I have",
+  "find / search notes about X", "read / open / summarize note X": call the
+  `skill` tool with `name: "apple-notes"` and `file: "references/read.md"`.
+- **Changing notes** — "add a note", "add to note X", "rewrite / replace note
+  X", "delete note X": call the `skill` tool with `name: "apple-notes"` and
+  `file: "references/write.md"`. It also covers how to get the note id that
+  edit and delete need.
+
+Most requests are ONE command. Run that single command, read its output, then
+answer — do not chain extra searches to "double-check" or enumerate. An
+empty-query search already lists every note; never enumerate notes by trying
+several queries.
+
+## When to Use
+
+- User explicitly mentions "Notes" (capital N), "Notes app", or "Apple Notes".
+- User wants a personal note that syncs to iCloud and shows up on their iPhone/iPad.
+- Note creation needs rich content (formatting, attachments) that Reminders cannot hold.
+
+## When NOT to Use
+
+- User wants a to-do or reminder (use the `apple-reminders` skill).
+- User wants a markdown vault, backlinks, or knowledge graph (use the `obsidian` skill).
+- User wants project tracking or shared docs (use Notion or another tool).
+- User just wants to dump text to a file (use the filesystem tools).
+
+## Setup
+
+- No install required. `osascript` ships with macOS.
+- Grant automation permission the first time: macOS prompts the user to allow
+  the parent terminal/app to control Notes. If denied, tell the user to enable it
+  under System Settings → Privacy & Security → Automation.
+
+## Output Policy
+
+- Note bodies are HTML: strip tags or convert to plain text before answering
+  unless the user asked for the raw markup. If the note is empty, say so.
+- Present search results as note names; keep the raw ids for follow-up
+  edit/delete calls rather than showing them to the user.
+- `execution error: Not authorized to send Apple events` → tell the user to
+  grant Automation permission in System Settings.
+- If the Notes app is not open and the operation fails, tell the user to open
+  Notes once (it usually auto-launches on first call).

package/skills/apple-notes/append-note.applescript

@@ -0,0 +1,9 @@
+-- Append an HTML fragment to a note found by name. argv: noteName, htmlFragment
+on run argv
+  set noteName to item 1 of argv
+  set extra to item 2 of argv
+  tell application "Notes"
+    set targetNote to first note whose name is noteName
+    set body of targetNote to (body of targetNote) & extra
+  end tell
+end run

package/skills/apple-notes/cli.schema.json

@@ -0,0 +1,32 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "x-positionals": ["script"],
+  "x-rest": "args",
+  "x-resource-files": [
+    "create-note.applescript",
+    "edit-note.applescript",
+    "append-note.applescript",
+    "read-note.applescript",
+    "search-notes.applescript",
+    "delete-note.applescript"
+  ],
+  "x-resource-effects": {
+    "read-note.applescript": "read",
+    "search-notes.applescript": "read"
+  },
+  "required": ["script", "args"],
+  "properties": {
+    "script": {
+      "type": "string",
+      "description": "absolute path to a bundled Apple Notes operation"
+    },
+    "args": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1,
+      "maxItems": 3,
+      "description": "argv passed to the bundled script"
+    }
+  }
+}

package/skills/apple-notes/create-note.applescript

@@ -0,0 +1,15 @@
+-- Create a Notes note. argv: name, htmlBody, [folder]
+-- Notes writes the `name` property as the body's first line, so creating with
+-- both name and body renders the title twice. Create from body, then rename.
+on run argv
+  set noteName to item 1 of argv
+  set noteBody to item 2 of argv
+  tell application "Notes"
+    if (count of argv) > 2 then
+      set newNote to make new note at folder (item 3 of argv) with properties {body:noteBody}
+    else
+      set newNote to make new note with properties {body:noteBody}
+    end if
+    set name of newNote to noteName
+  end tell
+end run

package/skills/apple-notes/delete-note.applescript

@@ -0,0 +1,10 @@
+-- Delete a note by its stable CoreData id. argv: noteId
+-- Id-based, not name-based: names collide, and delete is destructive. The note
+-- moves to Recently Deleted (restorable for 30 days). Get the id from
+-- search-notes.applescript.
+on run argv
+  set noteId to item 1 of argv
+  tell application "Notes"
+    delete note id noteId
+  end tell
+end run

package/skills/apple-notes/edit-note.applescript

@@ -0,0 +1,10 @@
+-- Replace a note's body by CoreData id. argv: noteId, replacementHtmlBody
+-- The replacement body must include the title as its first heading; replacing
+-- body without it also replaces the note's visible title.
+on run argv
+  set noteId to item 1 of argv
+  set replacementBody to item 2 of argv
+  tell application "Notes"
+    set body of note id noteId to replacementBody
+  end tell
+end run

package/skills/apple-notes/read-note.applescript

@@ -0,0 +1,28 @@
+-- Read a note's HTML body. argv: noteRef — a CoreData id (from search-notes,
+-- exact and preferred) or a note name. Name matching tries an exact title, then
+-- a contains match (Notes derives the title from rich text, so it can carry
+-- stray whitespace). Both paths — an id that no longer resolves and a name
+-- that matches nothing — report cleanly instead of raising an AppleScript
+-- error (-1728 / -1719) on a missing note or an empty selection.
+on run argv
+  set noteRef to item 1 of argv
+  tell application "Notes"
+    if noteRef starts with "x-coredata://" then
+      -- An id copied from a truncated search line, or one whose note was
+      -- deleted, no longer resolves; report cleanly rather than raising -1728.
+      try
+        return body of note id noteRef
+      on error
+        return "No note found matching: " & noteRef
+      end try
+    end if
+    set matches to notes whose name is noteRef
+    if (count of matches) is 0 then
+      set matches to notes whose name contains noteRef
+    end if
+    if (count of matches) is 0 then
+      return "No note found matching: " & noteRef
+    end if
+    return body of item 1 of matches
+  end tell
+end run

package/skills/apple-notes/references/read.md

@@ -0,0 +1,65 @@
+# Finding and Reading Notes
+
+Two bundled operations cover every read request. Run one per `exec` call as
+`osascript {{SKILL_DIR}}/<file>.applescript <args...>`.
+
+| Request                                   | Command                                             |
+| ----------------------------------------- | --------------------------------------------------- |
+| "list my notes" / "what notes do I have"  | `search-notes.applescript ""` — run it exactly ONCE |
+| "find / search notes about X"             | `search-notes.applescript "X"`                      |
+| "read / open / summarize note X"          | search first, then `read-note.applescript "<id>"`   |
+
+## Search Notes
+
+Pass a search term to `search-notes.applescript` (argv: query). It returns one
+match per line as `<id>\t<name>` for every note whose name OR body contains the
+term. Use the `name` to read a note, or the `id` to edit or delete it — this is
+the only bundled way to obtain a note's stable id.
+
+```bash
+osascript {{SKILL_DIR}}/search-notes.applescript "deadline"
+osascript {{SKILL_DIR}}/search-notes.applescript ""
+```
+
+An empty query (`""`) matches every note, so it doubles as "list all notes" — a
+single call returns the complete list. Run search ONCE per request; do not fire
+several searches (`""`, then `"meeting"`, then `""` again) to enumerate or
+re-confirm. A large library can exceed the default output cap: pass
+`maxOutputChars` (up to 65536) on the exec call, and if the output still ends in
+`… [truncated]`, tell the user the list is partial rather than presenting it as
+the whole library.
+
+## Read a Note
+
+Pass a note reference to `read-note.applescript` (argv: noteRef). It returns the
+note's HTML body. The reference is either a CoreData id or a note name:
+
+- **Prefer the id** from `search-notes.applescript` — it is exact. To read a
+  specific note, search first, then read by the id from that result.
+- A **name** works too, but is a fallback: Notes derives titles from rich text,
+  so exact-match can miss. Do not invent a name; use one search returned.
+
+```bash
+osascript {{SKILL_DIR}}/read-note.applescript "x-coredata://.../ICNote/p67"
+osascript {{SKILL_DIR}}/read-note.applescript "Meeting Notes"
+```
+
+When the user names one note, read exactly ONE note — the single best match
+from search — then answer and STOP. Do not read other notes to "explore" or
+compare, and never walk a previous list of notes reading them one by one. Only
+read more than one note when the user explicitly asked about several.
+
+A reference that matches nothing — a name with no match, or an id that no
+longer resolves (deleted, or copied from a truncated search line) — returns
+`No note found matching: ...` (not an error); search again and retry with the id
+from that result. The body is HTML; strip tags or convert to plain text before
+answering unless the user asked for the raw markup. A long note can exceed the
+default output cap: pass `maxOutputChars` (up to 65536) on the exec call, and if
+the body still ends in `… [truncated]`, tell the user it is partial rather than
+summarizing it as complete.
+
+## Common Mistakes
+
+- Using `title of note` — Notes has no `title` property. Read or search `name`.
+- Running several searches for one request — one `search-notes ""` is the whole list.
+- Reading every note from a list when the user asked about one.