Authoring Plugins in TypeScript

Authoring Plugins in TypeScript

TypeScript plugins for Ash are compiled into executable Node.js scripts (with #!/usr/bin/env node shebang) placed in ~/.ash/plugins/.

Requirements Implementation in TypeScript

1. AI Capability Discovery (--ai-docs):
   • Inspect process.argv for --ai-docs and print JSON documentation with JSON.stringify(docs, null, 2).
2. Standard CLI Flags (--version, --help):
   • Return semantic version and usage instructions.
3. Structured Logging Integration:
   • Check process.env.ASH_LOG_FILE, process.env.ASH_LOG_FORMAT, and process.env.ASH_VERBOSE.
   • Append structured JSON log entries containing an EID attribute.
4. Standalone Packaging:
   • Compile via tsc to a JavaScript bundle starting with #!/usr/bin/env node and make it executable (chmod 755).

Example TypeScript Plugin (src/index.ts)

#!/usr/bin/env node
import * as fs from "node:fs";
import * as process from "node:process";

const PLUGIN_NAME = "my_ts_plugin";
const VERSION = "1.0.0";

if (process.argv.includes("--ai-docs")) {
  console.log(JSON.stringify({
    Capabilities: ["TypeScript plugin capabilities."],
    Arguments: {
      "--ai-docs": "Print AI documentation",
      "--version": "Print version",
      "--help": "Print help"
    },
    "Return format": { status: "success", result: "data" }
  }, null, 2));
  process.exit(0);
}

if (process.argv.includes("--version") || process.argv.includes("-v")) {
  console.log(`${PLUGIN_NAME} ${VERSION}`);
  process.exit(0);
}

if (process.argv.includes("--help") || process.argv.includes("-h")) {
  console.log(`Usage: ${PLUGIN_NAME} [options]`);
  process.exit(0);
}

// Main logic
console.log("Hello from TypeScript plugin!");

Directory Structure and Makefile

internal/app/ash_bootstrap/plugins_src/my_ts_plugin/
├── Makefile
├── README.md
├── package.json
├── tsconfig.json
└── src/
    └── index.ts

Example Makefile:

PLUGIN_NAME := my_ts_plugin
BUILD_DIR ?= ../../../../../bin/plugins
OUTPUT_PATH ?= $(BUILD_DIR)/$(PLUGIN_NAME)

.PHONY: all build test lint clean

all: build

build:
	@mkdir -p "$(BUILD_DIR)"
	@if [ ! -d node_modules ]; then npm install; fi
	@npx tsc
	@cp dist/index.js "$(OUTPUT_PATH)"
	@chmod 755 "$(OUTPUT_PATH)"

test:
	@node dist/index.js --ai-docs >/dev/null

lint:
	@npx tsc --noEmit

clean:
	@rm -rf dist "$(OUTPUT_PATH)"