@codio-ai/opencode-authoring-agent 0.1.2 → 0.1.3

package/dist/tools/fetch-course.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export declare const fetchCourseInputSchema: z.ZodObject<{
+    workspace: z.ZodString;
+    courseId: z.ZodString;
+    outputDir: z.ZodOptional<z.ZodString>;
+    domain: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type FetchCourseInput = z.infer<typeof fetchCourseInputSchema>;
+export interface FetchCourseResult {
+    outputDir: string;
+    manifestPath: string;
+    assignmentsCsvPath: string;
+    moduleCount: number;
+    assignmentCount: number;
+}
+export declare function fetchCourseHandler(raw: unknown): Promise<FetchCourseResult>;
+//# sourceMappingURL=fetch-course.d.ts.map

package/dist/tools/fetch-course.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-course.d.ts","sourceRoot":"","sources":["../../src/tools/fetch-course.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,sBAAsB;;;;;iBAQjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB;AAoED,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAoGjF"}

package/dist/tools/fetch-course.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fetch-course.test.d.ts.map

package/dist/tools/fetch-course.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-course.test.d.ts","sourceRoot":"","sources":["../../src/tools/fetch-course.test.ts"],"names":[],"mappings":""}

package/dist/tools/index.d.ts

@@ -58,5 +58,41 @@ export declare const validate_guide: {
         workspace: string;
     }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
 };
+export declare const fetch_course: {
+    description: string;
+    args: {
+        workspace: import("zod").ZodString;
+        courseId: import("zod").ZodString;
+        outputDir: import("zod").ZodOptional<import("zod").ZodString>;
+        domain: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    execute(args: {
+        workspace: string;
+        courseId: string;
+        outputDir?: string | undefined;
+        domain?: string | undefined;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+};
+export declare const publish_course: {
+    description: string;
+    args: {
+        manifestPath: import("zod").ZodString;
+        dryRun: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        force: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        module: import("zod").ZodOptional<import("zod").ZodString>;
+        assignment: import("zod").ZodOptional<import("zod").ZodString>;
+        changelog: import("zod").ZodOptional<import("zod").ZodString>;
+        stack: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    execute(args: {
+        manifestPath: string;
+        dryRun?: boolean | undefined;
+        force?: boolean | undefined;
+        module?: string | undefined;
+        assignment?: string | undefined;
+        changelog?: string | undefined;
+        stack?: string | undefined;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+};
 export declare const tools: Record<string, unknown>;
 //# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAOtB,CAAC;AAOH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;CAkB5B,CAAC;AAIH,eAAO,MAAM,cAAc;;;;;;;;CAOzB,CAAC;AAQH,eAAO,MAAM,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAIzC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAOtB,CAAC;AAOH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;CAkB5B,CAAC;AAIH,eAAO,MAAM,cAAc;;;;;;;;CAOzB,CAAC;AAIH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;CAOvB,CAAC;AAIH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;CAOzB,CAAC;AAQH,eAAO,MAAM,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAMzC,CAAC"}

package/dist/tools/publish-course.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+export declare const publishCourseInputSchema: z.ZodObject<{
+    manifestPath: z.ZodString;
+    dryRun: z.ZodOptional<z.ZodBoolean>;
+    force: z.ZodOptional<z.ZodBoolean>;
+    module: z.ZodOptional<z.ZodString>;
+    assignment: z.ZodOptional<z.ZodString>;
+    changelog: z.ZodOptional<z.ZodString>;
+    stack: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PublishCourseInput = z.infer<typeof publishCourseInputSchema>;
+export interface PublishCourseResult {
+    published: number;
+    created: number;
+    unchanged: number;
+    skipped: number;
+    dryRun: boolean;
+}
+export declare function publishCourseHandler(raw: unknown): Promise<PublishCourseResult>;
+//# sourceMappingURL=publish-course.d.ts.map

package/dist/tools/publish-course.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-course.d.ts","sourceRoot":"","sources":["../../src/tools/publish-course.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,wBAAwB;;;;;;;;iBAQnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AA6DD,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAoHrF"}

package/dist/tools/publish-course.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=publish-course.test.d.ts.map

package/dist/tools/publish-course.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-course.test.d.ts","sourceRoot":"","sources":["../../src/tools/publish-course.test.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codio-ai/opencode-authoring-agent",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Opencode plugin for authoring Codio guide assignments — orchestrator, subagents, tools, and skills.",
   "type": "module",
   "main": "dist/index.js",
@@ -17,7 +17,7 @@
     "codio-authoring-unregister": "./bin/codio-authoring-unregister.js"
   },
   "scripts": {
-    "build": "bun build src/index.ts --outdir dist --target node --format esm --external @opencode-ai/plugin --external @opencode-ai/sdk --external zod && bun build src/codio-scripts/codio-fetch.js src/codio-scripts/codio-publish.js --outdir dist/codio-scripts --target node --format esm && tsc --emitDeclarationOnly",
+    "build": "bun build src/index.ts --outdir dist --target node --format esm --external @opencode-ai/plugin --external @opencode-ai/sdk --external zod && tsc --emitDeclarationOnly",
     "postinstall": "node ./bin/codio-authoring-register.js || true",
     "preuninstall": "node ./bin/codio-authoring-unregister.js || true",
     "test": "bun test",

package/src/skills/reference-codio-api/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: reference-codio-api
+description: Reference for the Codio platform API tools — fetch_course and publish_course. Course manifest format, output structure, credential requirements, and troubleshooting. Use when working with fetched courses or publishing assignments.
+---
+
+# Codio API Tools Reference
+
+## Credentials
+
+Both tools read credentials from environment variables. Set these on the Codio box before using either tool:
+
+| Variable | Required | Description |
+|---|---|---|
+| `CODIO_CLIENT_ID` | Yes | Codio API client ID |
+| `CODIO_CLIENT_SECRET` | Yes | Codio API client secret |
+| `CODIO_DOMAIN` | No | Codio domain, default `codio.com` |
+
+---
+
+## `fetch_course` — Pull a course from Codio
+
+Authenticates with the Codio API, downloads the course export, and writes an AI-ready project to the workspace.
+
+### Inputs
+
+| Field | Required | Description |
+|---|---|---|
+| `workspace` | Yes | Absolute path to the Codio workspace root |
+| `courseId` | Yes | Codio course ID (32-char hex string) |
+| `outputDir` | No | Output folder name, default `course-project` |
+| `domain` | No | Codio domain, default `codio.com` |
+
+### Output
+
+Returns `{ outputDir, manifestPath, assignmentsCsvPath, moduleCount, assignmentCount }`.
+
+Writes to `<outputDir>/` inside the workspace:
+
+```
+<outputDir>/
+├── course-manifest.json       ← machine-readable index; source of truth for publish_course
+├── course-assignments.csv     ← flat CSV for review
+└── course-content/
+    └── <module-folder>/
+        └── <assignment-folder>/
+            └── .guides/       ← guide pages, assessments, images
+```
+
+---
+
+## `publish_course` — Push assignments back to Codio
+
+Reads `course-manifest.json` from the project folder and publishes each assignment to Codio.
+
+### Inputs
+
+| Field | Required | Description |
+|---|---|---|
+| `manifestPath` | Yes | Absolute path to `course-manifest.json` |
+| `dryRun` | No | Preview actions without making changes |
+| `force` | No | Publish all, bypassing change detection |
+| `module` | No | Only process this module (name or folder) |
+| `assignment` | No | Only process this assignment (name or folder) |
+| `changelog` | No | Changelog text applied to all publishes |
+| `stack` | No | Force a specific stack ID for all assignments |
+
+### Output
+
+Returns `{ published, created, unchanged, skipped }`.
+
+Writes back any new IDs to `course-manifest.json` immediately after each resource is created.
+
+### Change detection
+
+The tool skips existing assignments whose content hash matches the stored `contentHash` in the manifest. Pass `force: true` to bypass. New assignments (no `id`) are always published.
+
+### Stacks
+
+- **New assignments** always use the default stack.
+- **Existing assignments** preserve their current stack unless `stack` is supplied.
+
+---
+
+## course-manifest.json format
+
+Created by `fetch_course`, consumed by `publish_course`. Both tools write back IDs as resources are created/resolved.
+
+```jsonc
+{
+  "schemaVersion": 2,
+  "courseId": "c87b4540de108faad55c8cefe7847492",
+  "exportedAt": "2026-06-12T10:00:00.000Z",
+  "counts": { "modules": 2, "assignments": 6 },
+  "paths": {
+    "assignmentsCsv": "course-assignments.csv",
+    "courseContent": "course-content"
+  },
+  "modules": [
+    {
+      "id": "...",             // Resolved or created by publish_course; written back
+      "name": "Module Name",
+      "folder": "module-name",
+      "path": "course-content/module-name",
+      "assignmentCount": 3,
+      "assignments": [
+        {
+          "id": "...",          // Created by publish_course if empty; written back
+          "name": "Assignment Name",
+          "folder": "assignment-name",
+          "path": "course-content/module-name/assignment-name",
+          "contentHash": "..."  // Written after each successful publish; used for change detection
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Folder slug rules
+
+Codio uses lowercase slugs: normalise to ASCII, lowercase, replace each non-alphanumeric character with `-`, trim leading/trailing hyphens. Example: `"1.1 – Intro"` → `"1-1---intro"`.
+
+---
+
+## Typical workflow
+
+```
+fetch_course(courseId)
+  → course-project/course-manifest.json + course-content/...
+
+[edit assignment pages using authoring tools]
+
+publish_course(manifestPath, dryRun: true)   ← preview first
+publish_course(manifestPath)                 ← publish for real
+```
+
+---
+
+## Troubleshooting
+
+| Error | Fix |
+|---|---|
+| `CODIO_CLIENT_ID ... must be set` | Set env vars on the box |
+| `course-manifest.json not found` | Pass the absolute path to the manifest; run from or inside the project folder |
+| `path not found` for an assignment | The folder referenced in the manifest doesn't exist — generate content there first |
+| `Required command not found: unzip` | Install `unzip` via the box package manager |
+| API 401 / auth error | Credentials are invalid or expired |
+| API 429 rate limit | Library retries automatically; wait and re-run if still failing |
+| `no module ID available` | Module creation failed earlier in the run — check the error above it |

package/src/skills/codio-fetch/SKILL.md

@@ -1,153 +0,0 @@
----
-name: codio-fetch
-description: Fetch and export an existing Codio course into an AI-ready local project. Use when the user asks to fetch, export, download, pull, or import a course from Codio, or to create a local AI-ready project from an existing Codio course.
-argument-hint: [--course-id <id>] [--output-dir <path>] [--domain <domain>]
-allowed-tools: [Bash, Read, Write, Edit]
----
-
-# Codio Fetch
-
-Export an existing Codio course into a clean, AI-ready local project that can be edited and re-published with `codio-publish`.
-
-## What this skill does
-
-1. Loads credentials from `.env` at the workspace root (the Codio assignment directory).
-2. Authenticates with the Codio API using `CODIO_CLIENT_ID` and `CODIO_CLIENT_SECRET`.
-3. Fetches course metadata and builds a `course-manifest.json` with all module and assignment IDs.
-4. Downloads the course source export ZIP from Codio.
-5. Extracts the ZIP into `course-content/`, expanding nested `.tar.zst` assignment archives.
-6. Writes `course-assignments.csv` as a flat index for easy review.
-7. Cleans up temporary download files.
-
-The output is a self-contained project folder ready for `codio-publish` to read back.
-
-## Output structure
-
-```
-<output-dir>/                  ← default: ./course-project
-├── course-manifest.json       ← machine-readable index with all IDs and paths
-├── course-assignments.csv     ← flat CSV listing all modules and assignments
-└── course-content/
-    └── <module-folder>/
-        └── <assignment-folder>/
-            └── .guides/       ← guide pages, assessments, images
-```
-
-The `<output-dir>` is always a named subfolder, never at the workspace root itself.
-
-## Prerequisites
-
-Before running, verify:
-
-1. **`.env` file** — must exist at the workspace root:
-   ```
-   CODIO_CLIENT_ID=your-client-id
-   CODIO_CLIENT_SECRET=your-client-secret
-   CODIO_COURSE_ID=your-course-id      # optional if passing --course-id
-   CODIO_DOMAIN=codio.com              # optional, defaults to codio.com
-   ```
-   The script finds `.env` by walking up from the current directory, so it works from anywhere inside the workspace.
-
-2. **Check `.env` is in place:**
-   ```bash
-   [ -f .env ] && echo "found" || echo "missing — create .env before running"
-   ```
-
-3. **Required system tools:** `node`, `unzip`, `tar`, `find`
-
-## Running the export
-
-Run from the workspace root (the Codio assignment directory):
-
-```bash
-bash ~/.config/opencode/skills/codio-fetch/scripts/run-course-export.sh --course-id <id>
-```
-
-### Options
-
-| Option | Description |
-|---|---|
-| `--course-id <id>` | Codio course ID (overrides `CODIO_COURSE_ID` from `.env`) |
-| `--output-dir <path>` | Output project folder (default: `./course-project`) |
-| `--domain <domain>` | Codio domain (default: `codio.com` or `CODIO_DOMAIN` from `.env`) |
-
-### Examples
-
-```bash
-# Use course ID from .env, output to ./course-project
-bash ~/.config/opencode/skills/codio-fetch/scripts/run-course-export.sh
-
-# Specify course ID and custom output folder
-bash ~/.config/opencode/skills/codio-fetch/scripts/run-course-export.sh \
-  --course-id c87b4540de108faad55c8cefe7847492 \
-  --output-dir ./my-java-course
-
-# Use a staging Codio domain
-bash ~/.config/opencode/skills/codio-fetch/scripts/run-course-export.sh \
-  --course-id c87b4540de108faad55c8cefe7847492 \
-  --domain codio.co.uk
-```
-
-## How credentials are loaded
-
-The shell script walks up from the current directory looking for `.env`, then sources it with `set -a; . .env; set +a`. Values in `.env` **override** anything already in the environment.
-
-The `.env` is shared across all Codio skills (`codio-fetch`, `codio-publish`). There is one `.env` at the workspace root, not one per skill.
-
-## Environment variables
-
-| Variable | Required | Description |
-|---|---|---|
-| `CODIO_CLIENT_ID` | Yes | Codio API client ID |
-| `CODIO_CLIENT_SECRET` | Yes | Codio API client secret |
-| `CODIO_COURSE_ID` | No | Course ID (can be passed as `--course-id` instead) |
-| `CODIO_DOMAIN` | No | Codio domain, default `codio.com` |
-
-## After the export
-
-- Open `<output-dir>/course-manifest.json` to see the full module/assignment hierarchy with IDs.
-- Open `<output-dir>/course-assignments.csv` for a flat spreadsheet view.
-- Assignment content is in `<output-dir>/course-content/<module>/<assignment>/`.
-- Use `codio-publish` to push edits back to Codio — the manifest with existing IDs is already in place.
-
-## Troubleshooting
-
-| Error | Fix |
-|---|---|
-| `Missing required environment variable: CODIO_CLIENT_ID` | Create or fix `.env` at workspace root |
-| `Missing course id` | Pass `--course-id <id>` or set `CODIO_COURSE_ID` in `.env` |
-| `Required command not found: unzip` | Install `unzip` via your package manager |
-| API 401 / auth error | Credentials in `.env` are invalid or expired |
-
-## Manifest format
-
-`course-manifest.json` produced by this skill is directly compatible with `codio-publish`. All assignment IDs are pre-populated, so a subsequent publish run will update existing assignments rather than create new ones.
-
-```jsonc
-{
-  "schemaVersion": 2,
-  "courseId": "...",
-  "exportedAt": "...",
-  "counts": { "modules": 2, "assignments": 6 },
-  "paths": {
-    "assignmentsCsv": "course-assignments.csv",
-    "courseContent": "course-content"
-  },
-  "modules": [
-    {
-      "name": "Module Name",
-      "folder": "module-name",
-      "path": "course-content/module-name",
-      "assignmentCount": 3,
-      "assignments": [
-        {
-          "id": "...",
-          "name": "Assignment Name",
-          "folder": "assignment-name",
-          "path": "course-content/module-name/assignment-name"
-        }
-      ]
-    }
-  ]
-}
-```

package/src/skills/codio-fetch/scripts/extract-course-export.sh

@@ -1,69 +0,0 @@
-#!/usr/bin/env bash
-set -Eeuo pipefail
-shopt -s nullglob
-
-log() {
-  printf '[%s] %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$*"
-}
-
-fail() {
-  log "ERROR: $*"
-  exit 1
-}
-
-require_command() {
-  command -v "$1" >/dev/null 2>&1 || fail "Required command not found: $1"
-}
-
-extract_assignment_archives() {
-  local root_dir="$1"
-  local archive_count=0
-
-  while IFS= read -r -d '' archive_path; do
-    archive_count=$((archive_count + 1))
-
-    local archive_dir archive_name destination_dir
-    archive_dir="$(dirname "$archive_path")"
-    archive_name="$(basename "$archive_path")"
-    destination_dir="$archive_dir/${archive_name%.tar.zst}"
-
-    rm -rf "$destination_dir"
-    mkdir -p "$destination_dir"
-
-    log "Extracting nested archive ${archive_name}"
-    tar --zstd -xf "$archive_path" -C "$destination_dir"
-    rm -f "$archive_path"
-  done < <(find "$root_dir" -type f -name '*.tar.zst' -print0)
-
-  log "Expanded ${archive_count} nested assignment archive(s)"
-}
-
-main() {
-  require_command unzip
-  require_command tar
-  require_command find
-  require_command cp
-
-  local export_zip_path="${1:-}"
-  local staging_dir="${2:-}"
-  local visible_output_dir="${3:-}"
-
-  [[ -n "$export_zip_path" ]]   || fail 'Usage: extract-course-export.sh <export-zip-path> <staging-dir> <visible-output-dir>'
-  [[ -n "$staging_dir" ]]       || fail 'Missing staging directory'
-  [[ -n "$visible_output_dir" ]] || fail 'Missing visible output directory'
-  [[ -f "$export_zip_path" ]]   || fail "Export ZIP not found: $export_zip_path"
-
-  rm -rf "$staging_dir" "$visible_output_dir"
-  mkdir -p "$staging_dir" "$visible_output_dir"
-
-  log "Unzipping $(basename "$export_zip_path") into hidden staging"
-  unzip -q "$export_zip_path" -d "$staging_dir"
-
-  extract_assignment_archives "$staging_dir"
-
-  cp -R "$staging_dir"/. "$visible_output_dir"
-
-  log "Published extracted course content to $visible_output_dir"
-}
-
-main "$@"