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

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

@@ -0,0 +1,196 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+FETCH_JS="$SCRIPT_DIR/codio-fetch.js"
+
+# Walk up from CWD to find .env; load it when found so credentials override env.
+# .env lives at the workspace root and is shared across all Codio skills.
+find_and_load_env() {
+  local dir
+  dir="$(pwd)"
+  while [[ "$dir" != "/" ]]; do
+    if [[ -f "$dir/.env" ]]; then
+      set -a
+      # shellcheck disable=SC1090
+      . "$dir/.env"
+      set +a
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  return 0  # .env is optional; continue without it
+}
+
+find_and_load_env
+
+OUTPUT_DIR=""
+COURSE_ID="${CODIO_COURSE_ID:-}"
+DOMAIN="${CODIO_DOMAIN:-codio.com}"
+
+log() {
+  printf '[%s] %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$*"
+}
+
+fail() {
+  log "ERROR: $*"
+  exit 1
+}
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  ./run-course-export.sh --course-id <id> [--output-dir <path>] [--domain <domain>]
+  CODIO_COURSE_ID=<id> ./run-course-export.sh
+
+Options:
+  --course-id <id>      Codio course ID (overrides CODIO_COURSE_ID from .env)
+  --output-dir <path>   Where to write the project folder (default: ./course-project)
+  --domain <domain>     Codio domain (default: codio.com or CODIO_DOMAIN from .env)
+
+Credentials (loaded from .env at workspace root):
+  CODIO_CLIENT_ID       Required
+  CODIO_CLIENT_SECRET   Required
+  CODIO_COURSE_ID       Optional — used when --course-id is not supplied
+  CODIO_DOMAIN          Optional — used when --domain is not supplied
+USAGE
+}
+
+require_command() {
+  command -v "$1" >/dev/null 2>&1 || fail "Required command not found: $1"
+}
+
+require_env() {
+  local name="$1"
+  [[ -n "${!name:-}" ]] || fail "Missing required environment variable: ${name}"
+}
+
+parse_args() {
+  while (($# > 0)); do
+    case "$1" in
+      --course-id)
+        [[ -n "${2:-}" ]] || fail 'Missing value for --course-id'
+        COURSE_ID="$2"; shift 2 ;;
+      --course-id=*)
+        COURSE_ID="${1#--course-id=}"; shift ;;
+      --output-dir)
+        [[ -n "${2:-}" ]] || fail 'Missing value for --output-dir'
+        OUTPUT_DIR="$2"; shift 2 ;;
+      --output-dir=*)
+        OUTPUT_DIR="${1#--output-dir=}"; shift ;;
+      --domain)
+        [[ -n "${2:-}" ]] || fail 'Missing value for --domain'
+        DOMAIN="$2"; shift 2 ;;
+      --domain=*)
+        DOMAIN="${1#--domain=}"; shift ;;
+      -h|--help)
+        usage; exit 0 ;;
+      --*)
+        fail "Unknown option: $1" ;;
+      *)
+        [[ -z "$COURSE_ID" ]] || fail 'Course ID was provided more than once'
+        COURSE_ID="$1"; shift ;;
+    esac
+  done
+}
+
+validate_manifest_paths() {
+  node - <<'NODE' "$VISIBLE_MANIFEST_JSON"
+const fs = require('node:fs');
+const path = require('node:path');
+
+const manifestPath = process.argv[2];
+const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+const root = path.dirname(manifestPath);
+const missing = [];
+
+for (const module of manifest.modules ?? []) {
+  const modulePath = path.join(root, module.path ?? '');
+  if (!fs.existsSync(modulePath) || !fs.statSync(modulePath).isDirectory()) {
+    missing.push(module.path ?? '');
+  }
+  for (const assignment of module.assignments ?? []) {
+    const assignmentPath = path.join(root, assignment.path ?? '');
+    if (!fs.existsSync(assignmentPath) || !fs.statSync(assignmentPath).isDirectory()) {
+      missing.push(assignment.path ?? '');
+    }
+  }
+}
+
+if (missing.length > 0) {
+  console.error('[manifest] WARNING: The following planned content paths were not found after extraction:');
+  for (const missingPath of missing) {
+    console.error(`[manifest]   - ${missingPath}`);
+  }
+}
+NODE
+}
+
+main() {
+  parse_args "$@"
+
+  require_command node
+  require_command unzip
+  require_command tar
+  require_command find
+
+  require_env CODIO_CLIENT_ID
+  require_env CODIO_CLIENT_SECRET
+  [[ -n "$COURSE_ID" ]] || fail 'Missing course id. Pass --course-id <id>, pass a positional id, or set CODIO_COURSE_ID in .env.'
+
+  [[ -f "$FETCH_JS" ]] || fail "codio-fetch.js not found at $FETCH_JS — reinstall the plugin."
+
+  # Resolve output directory to an absolute path
+  if [[ -z "$OUTPUT_DIR" ]]; then
+    OUTPUT_DIR="$(pwd)/course-project"
+  elif [[ "$OUTPUT_DIR" != /* ]]; then
+    OUTPUT_DIR="$(pwd)/$OUTPUT_DIR"
+  fi
+
+  VISIBLE_OUTPUT_DIR="$OUTPUT_DIR"
+  VISIBLE_CONTENT_DIR="$VISIBLE_OUTPUT_DIR/course-content"
+  VISIBLE_ASSIGNMENTS_CSV="$VISIBLE_OUTPUT_DIR/course-assignments.csv"
+  VISIBLE_MANIFEST_JSON="$VISIBLE_OUTPUT_DIR/course-manifest.json"
+
+  RUN_TIMESTAMP="$(date -u +%Y%m%dT%H%M%SZ)"
+  EXPORT_BASENAME="course-source-export-${RUN_TIMESTAMP}"
+  HIDDEN_WORK_DIR="$(mktemp -d)"
+  DOWNLOADS_DIR="$HIDDEN_WORK_DIR/downloads"
+  STAGING_DIR="$HIDDEN_WORK_DIR/staging"
+  EXPORT_ZIP_PATH="$DOWNLOADS_DIR/${EXPORT_BASENAME}.zip"
+  STAGING_EXTRACT_DIR="$STAGING_DIR/${EXPORT_BASENAME}"
+
+  rm -rf "$VISIBLE_OUTPUT_DIR"
+  mkdir -p "$VISIBLE_CONTENT_DIR" "$DOWNLOADS_DIR" "$STAGING_DIR"
+
+  log "Generating AI-ready course project"
+  log "Course ID:  ${COURSE_ID}"
+  log "Domain:     ${DOMAIN}"
+  log "Output:     ${VISIBLE_OUTPUT_DIR}"
+
+  node "$FETCH_JS" \
+    --course-id       "$COURSE_ID" \
+    --client-id       "$CODIO_CLIENT_ID" \
+    --client-secret   "$CODIO_CLIENT_SECRET" \
+    --domain          "$DOMAIN" \
+    --export-zip-path "$EXPORT_ZIP_PATH" \
+    --assignments-csv-path "$VISIBLE_ASSIGNMENTS_CSV" \
+    --manifest-path        "$VISIBLE_MANIFEST_JSON" \
+    --course-content-path  "$VISIBLE_CONTENT_DIR"
+
+  "$SCRIPT_DIR/extract-course-export.sh" \
+    "$EXPORT_ZIP_PATH" \
+    "$STAGING_EXTRACT_DIR" \
+    "$VISIBLE_CONTENT_DIR"
+
+  # Remove exported README.md files (Codio export artefacts, not assignment content)
+  find "$VISIBLE_OUTPUT_DIR" -type f -iname 'README.md' -delete
+
+  validate_manifest_paths
+
+  rm -rf "$HIDDEN_WORK_DIR"
+
+  log "Done. Project available at ${VISIBLE_OUTPUT_DIR}"
+}
+
+main "$@"

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

@@ -0,0 +1,140 @@
+---
+name: codio-publish
+description: Publish Codio course assignments to the Codio platform. Use when the user asks to publish, deploy, or upload assignments to Codio, or to sync course content with a Codio course. Reads course-manifest.json and creates courses, modules, and assignments as needed before publishing each one.
+argument-hint: [--force] [--module <name>] [--assignment <name>] [--dry-run] [--changelog <text>] [--course-name <name>] [--stack <stack-id>]
+allowed-tools: [Bash, Read, Write, Edit]
+---
+
+# Codio Publish
+
+Publish course assignments to Codio using `course-manifest.json` as the source of truth.
+
+## What this skill does
+
+1. Loads credentials from `.env` (walks up from CWD to find it), overriding any existing env vars.
+2. Reads `course-manifest.json` from the current working directory (the project folder).
+3. Creates a Codio course if `courseId` is missing.
+4. For each module: resolves or creates the module in Codio and records its ID.
+5. For each assignment: creates it in Codio if the `id` field is empty, then publishes it.
+   - New assignments (no prior ID) are published with the default stack.
+   - Existing assignments (already have an ID) are published without a stack unless `--stack` is passed.
+6. Writes back any new IDs to `course-manifest.json` immediately after each resource is created.
+
+## Project folder layout
+
+`course-manifest.json` and `course-content/` must live together inside a named project subfolder. The manifest must **not** be placed at the workspace root alone.
+
+```
+workspace/                     ← workspace root (contains .env)
+└── my-course/                 ← project folder — cd here before running
+    ├── course-manifest.json
+    └── course-content/
+        └── <module-folder>/
+            └── <assignment-folder>/
+                └── .guides/   ← or a .zip archive
+```
+
+Run the publish script from inside the project folder:
+```bash
+cd my-course
+node ~/.config/opencode/skills/codio-publish/scripts/codio-publish.js
+```
+
+## Prerequisites
+
+Before running, verify:
+
+1. **`.env` file** — must exist at the workspace root (the script walks up from CWD to find it):
+   ```
+   CODIO_CLIENT_ID=your-client-id
+   CODIO_CLIENT_SECRET=your-client-secret
+   CODIO_DOMAIN=codio.com              # optional, defaults to codio.com
+   ```
+   The `.env` is shared across all Codio skills — one file at the workspace root, not one per skill.
+
+   Check credentials are loaded:
+   ```bash
+   node ~/.config/opencode/skills/codio-publish/scripts/codio-publish.js --dry-run
+   ```
+
+2. **`course-manifest.json`** — must exist in the directory you run from (the project folder). If not found, tell the user.
+
+## Running the publish script
+
+Run from the project folder (the directory that contains `course-manifest.json`):
+
+```bash
+node ~/.config/opencode/skills/codio-publish/scripts/codio-publish.js [options]
+```
+
+### Options
+
+| Option | Description |
+|---|---|
+| `--force` | Publish all assignments regardless of whether content has changed |
+| `--dry-run` | Preview all actions without making any changes |
+| `--module <name>` | Only process assignments in this module (name or folder) |
+| `--assignment <name>` | Only process this assignment (name or folder) |
+| `--changelog <text>` | Changelog message applied to all publishes |
+| `--course-name <name>` | Course name to use when creating a new course |
+| `--stack <stack-id>` | Force a specific stack for all assignments in this run (overrides default) |
+
+### Example: dry run first, then publish
+
+```bash
+node ~/.config/opencode/skills/codio-publish/scripts/codio-publish.js --dry-run
+node ~/.config/opencode/skills/codio-publish/scripts/codio-publish.js
+```
+
+### Example: publish one module
+
+```bash
+node ~/.config/opencode/skills/codio-publish/scripts/codio-publish.js --module "Basic Skills"
+```
+
+### Example: publish one assignment
+
+```bash
+node ~/.config/opencode/skills/codio-publish/scripts/codio-publish.js --assignment "Printing"
+```
+
+### Example: publish with a custom stack
+
+```bash
+node ~/.config/opencode/skills/codio-publish/scripts/codio-publish.js --stack e0195698-d647-4490-8834-350583b532eb:latest
+```
+
+## Environment variables
+
+| 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` |
+
+## Assignment content
+
+The script looks for content in the `path` field of each assignment in the manifest (e.g. `course-content/basic-skills/printing`). It handles two layouts automatically:
+
+- **Zip archive** — the folder contains a `.zip` file. Published via `publishArchive`.
+- **Extracted guide** — the folder contains a `.guides/` directory or other files. Published via `publish`.
+
+## Stacks
+
+- **New assignments** (no `id` in the manifest) are always published with the default stack.
+- **Existing assignments** (already have an `id`) are published without a stack by default.
+- **`--stack <stack-id>`** forces a specific stack for all assignments in the current run.
+
+## Change detection (default behaviour)
+
+The script skips existing assignments whose content has not changed since the last publish. Change detection uses a SHA-256 fingerprint stored as `contentHash` in `course-manifest.json`. Pass `--force` to bypass it.
+
+## Troubleshooting
+
+| Error | Fix |
+|---|---|
+| `CODIO_CLIENT_ID ... must be set` | Create or fix `.env` at workspace root |
+| `course-manifest.json not found` | Run from the project folder, not the workspace root |
+| `path not found` for an assignment | The folder referenced in the manifest doesn't exist — generate or place content there first |
+| API 401 / auth error | Credentials in `.env` are invalid or expired |
+| API 429 rate limit | The library retries automatically; wait and re-run if it still fails |