@hncode/hncode-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,131 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

package/README.md

@@ -0,0 +1,183 @@
+# @hncode/hncode-sdk
+
+Types and runtime helpers for writing [hncode](https://npmjs.com/package/@hncode/hncode) plugins.
+
+A plugin runs **inside** the hncode process: the host calls your `install(api)` and
+hands you the `api` object. So a plugin never imports hncode itself — but at author
+time you want completion for `api.` and, for `api.patch`, the list of symbols you
+may target. That is what this package provides.
+
+- **`HncodePluginApi`** — the type of the `api` object (every method, its
+  signature and return).
+- **`PatchTarget`** — a literal union of every symbol a plugin may patch
+  (`'llm.js#LLM.requestText'`, `'git.js#commit'`, …), so the target string
+  completes and is checked.
+- **Runtime helpers** — `definePlugin`, `parsePatchTarget`, `HOOK_NAMES`,
+  `LEGACY_SEAMS`, and the generated `PATCH_TARGETS` list.
+
+It has **zero dependencies** and pulls in none of the CLI.
+
+## Install
+
+```bash
+npm i -D @hncode/hncode-sdk
+```
+
+## Write a plugin
+
+```js
+// plugins/hello/index.js
+import { definePlugin, HOOK_NAMES } from '@hncode/hncode-sdk';
+
+export default definePlugin({
+  name: 'hello',
+  version: '1.0.0',
+  install(api) {
+    api.registerCommand({
+      name: 'hello',
+      description: 'Say hello',
+      run: () => 'hi',
+    });
+  },
+});
+```
+
+In TypeScript (or with JSDoc `checkJs`), `api` is typed automatically once the
+plugin's default export is annotated:
+
+```ts
+import type { HncodePlugin } from '@hncode/hncode-sdk';
+
+const plugin: HncodePlugin = {
+  name: 'hello',
+  version: '1.0.0',
+  install(api) {
+    api.registerCommand({ name: 'hello', description: 'Say hello', run: () => 'hi' });
+  },
+};
+export default plugin;
+```
+
+## Patching hncode's own code
+
+`api.patch(target, handler)` wraps an exported function or class method in
+hncode's `src/` without editing it (the equivalent of a Minecraft mixin).
+
+```js
+import { isPatchTarget } from '@hncode/hncode-sdk/targets';
+
+export default {
+  name: 'audit', version: '1.0.0',
+  install(api) {
+    // `target` is typed as PatchTarget, so it completes.
+    api.patch('git.js#commit', {
+      before: (...args) => console.log('commit', args),
+      after: (result) => result,
+    });
+  },
+};
+```
+
+A handler may supply any of:
+
+- `before(...args)` — runs before the call. Return an array to **replace** the args.
+- `after(result, args)` — runs after. Return a non-`undefined` value to **replace** the result.
+- `around(original, args, this)` — full control; its return value is the result.
+
+Async functions are handled transparently.
+
+## Logging
+
+`api.log` is callable **and** carries the four methods, like `console`:
+
+```js
+api.log('plain call');          // -> an info notice
+api.log.warn('careful');        // -> a warning notice
+api.log.error('failed');
+```
+
+There are no separate `api.info` / `api.warn` / `api.error` members. Everything reaches
+the chat and is mirrored to the terminal, so a plugin author watching stderr sees it too.
+
+## Introspection
+
+What the current load has registered, live (not a snapshot):
+
+```js
+api.tools;      // ToolSpec[]  — including other plugins'
+api.commands;   // CommandSpec[]
+api.hooks;      // { [hookName]: fn[] }
+api.config;     // plugin-supplied defaults, before user overrides
+api.plugins;    // [{ name, version }] in install order
+```
+
+Useful for avoiding a name collision before calling `registerTool` / `registerCommand`.
+
+## Driving the UI
+
+```js
+api.openFileTree('src');   // the /files browser; false if it could not open
+api.closeFileTree();
+
+api.themeNames;            // ['auto','dark','light','nord','dracula','gruvbox','mono']
+api.getTheme();            // the one in force
+api.setTheme('gruvbox');   // false for an unknown name
+```
+
+`openFileTree` returns whether the browser actually opened. An empty workspace or a
+headless host gives `false`, so a plugin can tell rather than waiting on a panel that never
+appeared.
+
+## Subagents
+
+The same controls the model has as tools, for a plugin:
+
+```js
+for (const a of api.subagents()) {
+  // { id, runId, taskId, type, description, startedAt }
+}
+
+api.messageSubagent(a.id, 'also check the tests');  // { ok, message }
+api.interruptSubagent(a.id);                        // omit the id to stop all
+api.closeSubagent(a.id);                            // stop AND drop from the list
+```
+
+`api.subagents()` lists only what is running now — a finished agent is no longer
+controllable. The live handles (`steer`, `interrupt`) are not exposed; the calls above are
+the whole surface.
+
+## Keybindings
+
+```js
+api.isKeyBound('ctrl+t');  // true if a built-in, another plugin or the user took it
+api.boundKeys;             // every claimed token
+```
+
+`registerKeybind` overwrites silently, so check first if you want to be polite. Any
+spelling works — `'ctrl+t'` and `'c-t'` are the same key.
+
+## Lifecycle hooks
+
+`api.registerHook(name, fn)`. The names the host actually fires:
+
+`onStartup`, `onShutdown`, `onTurnStart`, `onTurnEnd`, `onBeforeRequest`,
+`onAfterRequest`, `onToolExecute`, `onToolResult`, `onNewMessage`, `onSessionSave`.
+
+`HOOK_NAMES` holds the same list at runtime.
+
+## Regenerating the target list
+
+`targets.js` / `targets.d.ts` are generated from the main package's `src/`, so they
+must be refreshed whenever the main package changes:
+
+```bash
+# from a checkout where hncode-sdk/ sits next to hncode's src/
+node scripts/gen-targets.mjs            # uses the parent directory
+node scripts/gen-targets.mjs D:\hncode  # or point at the root explicitly
+```
+
+This runs automatically on `prepublishOnly`.
+
+## License
+
+PolyForm Noncommercial 1.0.0 — same as hncode.