@atscript/typescript 0.1.19 → 0.1.20

package/dist/utils.cjs

@@ -553,7 +553,7 @@ function isAnnotatedTypeOfPrimitive(t) {
 //#endregion
 //#region packages/typescript/src/json-schema.ts
 function buildJsonSchema(type) {
-	const build = (def) => {
+	const build$1 = (def) => {
 		const meta = def.metadata;
 		return forAnnotatedType(def, {
 			phantom() {
@@ -564,7 +564,7 @@ function buildJsonSchema(type) {
 				const required = [];
 				for (const [key, val] of d.type.props.entries()) {
 					if (isPhantomType(val)) continue;
-					properties[key] = build(val);
+					properties[key] = build$1(val);
 					if (!val.optional) required.push(key);
 				}
 				const schema = {
@@ -577,7 +577,7 @@ function buildJsonSchema(type) {
 			array(d) {
 				const schema = {
 					type: "array",
-					items: build(d.type.of)
+					items: build$1(d.type.of)
 				};
 				const minLength = meta.get("expect.minLength");
 				if (minLength) schema.minItems = typeof minLength === "number" ? minLength : minLength.length;
@@ -586,15 +586,15 @@ function buildJsonSchema(type) {
 				return schema;
 			},
 			union(d) {
-				return { anyOf: d.type.items.map(build) };
+				return { anyOf: d.type.items.map(build$1) };
 			},
 			intersection(d) {
-				return { allOf: d.type.items.map(build) };
+				return { allOf: d.type.items.map(build$1) };
 			},
 			tuple(d) {
 				return {
 					type: "array",
-					items: d.type.items.map(build),
+					items: d.type.items.map(build$1),
 					additionalItems: false
 				};
 			},
@@ -625,7 +625,7 @@ else schema.allOf = (schema.allOf || []).concat(patterns.map((p) => ({ pattern:
 			}
 		});
 	};
-	return build(type);
+	return build$1(type);
 }
 function fromJsonSchema(schema) {
 	const convert = (s) => {
@@ -719,6 +719,86 @@ function fromJsonSchema(schema) {
 	return convert(schema);
 }
 
+//#endregion
+//#region packages/typescript/src/default-value.ts
+/**
+* Attempts to resolve a value from the mode for the given annotated type.
+* Returns `undefined` when no value is available (or parse/validation fails).
+*/ function resolveValue(prop, path, mode) {
+	if (!mode || mode === "empty") return undefined;
+	let raw;
+	if (typeof mode === "function") {
+		raw = mode(prop, path);
+		if (raw === undefined) return undefined;
+		if (prop.validator({ unknownProps: "ignore" }).validate(raw, true)) return { value: raw };
+		return undefined;
+	}
+	const metaKey = mode === "default" ? "meta.default" : "meta.example";
+	const rawStr = prop.metadata.get(metaKey);
+	if (rawStr === undefined) return undefined;
+	const parsed = parseRawValue(rawStr, prop);
+	if (parsed === undefined) return undefined;
+	if (prop.validator({ unknownProps: "ignore" }).validate(parsed, true)) return { value: parsed };
+	return undefined;
+}
+/**
+* Parses a raw annotation string into a JS value.
+* Strings are returned as-is for string types; everything else goes through JSON.parse.
+*/ function parseRawValue(raw, prop) {
+	if (prop.type.kind === "" && prop.type.designType === "string") return raw;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return undefined;
+	}
+}
+/** Returns the structural default for a final (primitive/literal) type. */ function finalDefault(def) {
+	if (def.type.value !== undefined) return def.type.value;
+	switch (def.type.designType) {
+		case "string": return "";
+		case "number": return 0;
+		case "boolean": return false;
+		case "undefined": return undefined;
+		case "null": return null;
+		default: return undefined;
+	}
+}
+function createDataFromAnnotatedType(type, opts) {
+	return build(type, "", opts?.mode);
+}
+function build(def, path, mode) {
+	const resolved = resolveValue(def, path, mode);
+	if (resolved !== undefined) return resolved.value;
+	return forAnnotatedType(def, {
+		phantom: () => undefined,
+		final: (d) => finalDefault(d),
+		object: (d) => {
+			const data = {};
+			for (const [key, prop] of d.type.props.entries()) {
+				if (isPhantomType(prop)) continue;
+				const childPath = path ? `${path}.${key}` : key;
+				if (prop.optional) {
+					const childResolved = resolveValue(prop, childPath, mode);
+					if (childResolved !== undefined) data[key] = childResolved.value;
+					continue;
+				}
+				data[key] = build(prop, childPath, mode);
+			}
+			return data;
+		},
+		array: () => [],
+		tuple: (d) => d.type.items.map((item, i) => build(item, `${path}.${i}`, mode)),
+		union: (d) => {
+			const first = d.type.items[0];
+			return first ? build(first, path, mode) : undefined;
+		},
+		intersection: (d) => {
+			const first = d.type.items[0];
+			return first ? build(first, path, mode) : undefined;
+		}
+	});
+}
+
 //#endregion
 //#region packages/typescript/src/flatten.ts
 function flattenAnnotatedType(type, options) {
@@ -969,6 +1049,7 @@ exports.Validator = Validator
 exports.ValidatorError = ValidatorError
 exports.annotate = annotate
 exports.buildJsonSchema = buildJsonSchema
+exports.createDataFromAnnotatedType = createDataFromAnnotatedType
 exports.defineAnnotatedType = defineAnnotatedType
 exports.deserializeAnnotatedType = deserializeAnnotatedType
 exports.flattenAnnotatedType = flattenAnnotatedType

package/dist/utils.d.ts

@@ -305,6 +305,43 @@ declare function forAnnotatedType<R>(def: TAtscriptAnnotatedType, handlers: {
     phantom?: (def: TAtscriptAnnotatedType<TAtscriptTypeFinal>) => R;
 }): R;
 
+/**
+ * Custom resolver function for computing field values.
+ * Return `undefined` to fall through to structural defaults.
+ */
+type TValueResolver = (prop: TAtscriptAnnotatedType, path: string) => unknown | undefined;
+/** Options for {@link createDataFromAnnotatedType}. */
+interface TCreateDataOptions {
+    /**
+     * How to resolve values:
+     * - `'empty'` — structural defaults only (`''`, `0`, `false`, `[]`, `{}`); optional props skipped
+     * - `'default'` — use `@meta.default` annotations; optional props skipped unless annotated
+     * - `'example'` — use `@meta.example` annotations; optional props skipped unless annotated
+     * - `function` — custom resolver per field; optional props skipped unless resolver returns a value
+     *
+     * @default 'empty'
+     */
+    mode?: 'empty' | 'default' | 'example' | TValueResolver;
+}
+/**
+ * Creates a data object from an ATScript annotated type definition.
+ *
+ * Supports four modes:
+ * - `'empty'` — structural defaults only; optional props omitted
+ * - `'default'` — uses `@meta.default` annotations; optional props omitted unless annotated
+ * - `'example'` — uses `@meta.example` annotations; optional props omitted unless annotated
+ * - `function` — custom resolver; optional props omitted unless resolver returns a value
+ *
+ * When a `@meta.default` / `@meta.example` value is set on a complex type (object, array)
+ * and passes full validation, the entire subtree is replaced — no recursion into inner props.
+ * If validation fails, the annotation is ignored and structural defaults are built from inner props.
+ *
+ * @param type - The ATScript annotated type to create data from.
+ * @param opts - Options controlling value resolution mode.
+ * @returns A value conforming to the type's shape.
+ */
+declare function createDataFromAnnotatedType(type: TAtscriptAnnotatedType, opts?: TCreateDataOptions): unknown;
+
 /**
  * Options for controlling the flattening process.
  */
@@ -452,5 +489,5 @@ declare function serializeAnnotatedType(type: TAtscriptAnnotatedType, options?:
  */
 declare function deserializeAnnotatedType(data: TSerializedAnnotatedType): TAtscriptAnnotatedType;
 
-export { SERIALIZE_VERSION, Validator, ValidatorError, annotate, buildJsonSchema, defineAnnotatedType, deserializeAnnotatedType, flattenAnnotatedType, forAnnotatedType, fromJsonSchema, isAnnotatedType, isAnnotatedTypeOfPrimitive, isPhantomType, serializeAnnotatedType };
-export type { InferDataType, TAnnotatedTypeHandle, TAtscriptAnnotatedType, TAtscriptAnnotatedTypeConstructor, TAtscriptTypeArray, TAtscriptTypeComplex, TAtscriptTypeDef, TAtscriptTypeFinal, TAtscriptTypeObject, TFlattenOptions, TMetadataMap, TProcessAnnotationContext, TSerializeOptions, TSerializedAnnotatedType, TSerializedAnnotatedTypeInner, TSerializedTypeArray, TSerializedTypeComplex, TSerializedTypeDef, TSerializedTypeFinal, TSerializedTypeObject, TValidatorOptions, TValidatorPlugin, TValidatorPluginContext };
+export { SERIALIZE_VERSION, Validator, ValidatorError, annotate, buildJsonSchema, createDataFromAnnotatedType, defineAnnotatedType, deserializeAnnotatedType, flattenAnnotatedType, forAnnotatedType, fromJsonSchema, isAnnotatedType, isAnnotatedTypeOfPrimitive, isPhantomType, serializeAnnotatedType };
+export type { InferDataType, TAnnotatedTypeHandle, TAtscriptAnnotatedType, TAtscriptAnnotatedTypeConstructor, TAtscriptTypeArray, TAtscriptTypeComplex, TAtscriptTypeDef, TAtscriptTypeFinal, TAtscriptTypeObject, TCreateDataOptions, TFlattenOptions, TMetadataMap, TProcessAnnotationContext, TSerializeOptions, TSerializedAnnotatedType, TSerializedAnnotatedTypeInner, TSerializedTypeArray, TSerializedTypeComplex, TSerializedTypeDef, TSerializedTypeFinal, TSerializedTypeObject, TValidatorOptions, TValidatorPlugin, TValidatorPluginContext, TValueResolver };

package/dist/utils.mjs

@@ -552,7 +552,7 @@ function isAnnotatedTypeOfPrimitive(t) {
 //#endregion
 //#region packages/typescript/src/json-schema.ts
 function buildJsonSchema(type) {
-	const build = (def) => {
+	const build$1 = (def) => {
 		const meta = def.metadata;
 		return forAnnotatedType(def, {
 			phantom() {
@@ -563,7 +563,7 @@ function buildJsonSchema(type) {
 				const required = [];
 				for (const [key, val] of d.type.props.entries()) {
 					if (isPhantomType(val)) continue;
-					properties[key] = build(val);
+					properties[key] = build$1(val);
 					if (!val.optional) required.push(key);
 				}
 				const schema = {
@@ -576,7 +576,7 @@ function buildJsonSchema(type) {
 			array(d) {
 				const schema = {
 					type: "array",
-					items: build(d.type.of)
+					items: build$1(d.type.of)
 				};
 				const minLength = meta.get("expect.minLength");
 				if (minLength) schema.minItems = typeof minLength === "number" ? minLength : minLength.length;
@@ -585,15 +585,15 @@ function buildJsonSchema(type) {
 				return schema;
 			},
 			union(d) {
-				return { anyOf: d.type.items.map(build) };
+				return { anyOf: d.type.items.map(build$1) };
 			},
 			intersection(d) {
-				return { allOf: d.type.items.map(build) };
+				return { allOf: d.type.items.map(build$1) };
 			},
 			tuple(d) {
 				return {
 					type: "array",
-					items: d.type.items.map(build),
+					items: d.type.items.map(build$1),
 					additionalItems: false
 				};
 			},
@@ -624,7 +624,7 @@ else schema.allOf = (schema.allOf || []).concat(patterns.map((p) => ({ pattern:
 			}
 		});
 	};
-	return build(type);
+	return build$1(type);
 }
 function fromJsonSchema(schema) {
 	const convert = (s) => {
@@ -718,6 +718,86 @@ function fromJsonSchema(schema) {
 	return convert(schema);
 }
 
+//#endregion
+//#region packages/typescript/src/default-value.ts
+/**
+* Attempts to resolve a value from the mode for the given annotated type.
+* Returns `undefined` when no value is available (or parse/validation fails).
+*/ function resolveValue(prop, path, mode) {
+	if (!mode || mode === "empty") return undefined;
+	let raw;
+	if (typeof mode === "function") {
+		raw = mode(prop, path);
+		if (raw === undefined) return undefined;
+		if (prop.validator({ unknownProps: "ignore" }).validate(raw, true)) return { value: raw };
+		return undefined;
+	}
+	const metaKey = mode === "default" ? "meta.default" : "meta.example";
+	const rawStr = prop.metadata.get(metaKey);
+	if (rawStr === undefined) return undefined;
+	const parsed = parseRawValue(rawStr, prop);
+	if (parsed === undefined) return undefined;
+	if (prop.validator({ unknownProps: "ignore" }).validate(parsed, true)) return { value: parsed };
+	return undefined;
+}
+/**
+* Parses a raw annotation string into a JS value.
+* Strings are returned as-is for string types; everything else goes through JSON.parse.
+*/ function parseRawValue(raw, prop) {
+	if (prop.type.kind === "" && prop.type.designType === "string") return raw;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return undefined;
+	}
+}
+/** Returns the structural default for a final (primitive/literal) type. */ function finalDefault(def) {
+	if (def.type.value !== undefined) return def.type.value;
+	switch (def.type.designType) {
+		case "string": return "";
+		case "number": return 0;
+		case "boolean": return false;
+		case "undefined": return undefined;
+		case "null": return null;
+		default: return undefined;
+	}
+}
+function createDataFromAnnotatedType(type, opts) {
+	return build(type, "", opts?.mode);
+}
+function build(def, path, mode) {
+	const resolved = resolveValue(def, path, mode);
+	if (resolved !== undefined) return resolved.value;
+	return forAnnotatedType(def, {
+		phantom: () => undefined,
+		final: (d) => finalDefault(d),
+		object: (d) => {
+			const data = {};
+			for (const [key, prop] of d.type.props.entries()) {
+				if (isPhantomType(prop)) continue;
+				const childPath = path ? `${path}.${key}` : key;
+				if (prop.optional) {
+					const childResolved = resolveValue(prop, childPath, mode);
+					if (childResolved !== undefined) data[key] = childResolved.value;
+					continue;
+				}
+				data[key] = build(prop, childPath, mode);
+			}
+			return data;
+		},
+		array: () => [],
+		tuple: (d) => d.type.items.map((item, i) => build(item, `${path}.${i}`, mode)),
+		union: (d) => {
+			const first = d.type.items[0];
+			return first ? build(first, path, mode) : undefined;
+		},
+		intersection: (d) => {
+			const first = d.type.items[0];
+			return first ? build(first, path, mode) : undefined;
+		}
+	});
+}
+
 //#endregion
 //#region packages/typescript/src/flatten.ts
 function flattenAnnotatedType(type, options) {
@@ -963,4 +1043,4 @@ function deserializeTypeDef(t) {
 }
 
 //#endregion
-export { SERIALIZE_VERSION, Validator, ValidatorError, annotate, buildJsonSchema, defineAnnotatedType, deserializeAnnotatedType, flattenAnnotatedType, forAnnotatedType, fromJsonSchema, isAnnotatedType, isAnnotatedTypeOfPrimitive, isPhantomType, serializeAnnotatedType };
+export { SERIALIZE_VERSION, Validator, ValidatorError, annotate, buildJsonSchema, createDataFromAnnotatedType, defineAnnotatedType, deserializeAnnotatedType, flattenAnnotatedType, forAnnotatedType, fromJsonSchema, isAnnotatedType, isAnnotatedTypeOfPrimitive, isPhantomType, serializeAnnotatedType };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/typescript",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "Atscript: typescript-gen support.",
   "keywords": [
     "annotations",
@@ -19,11 +19,14 @@
     "directory": "packages/typescript"
   },
   "bin": {
-    "asc": "./cli.cjs"
+    "asc": "./cli.cjs",
+    "setup-skills": "./scripts/setup-skills.js"
   },
   "files": [
     "dist",
-    "cli.cjs"
+    "cli.cjs",
+    "skills",
+    "scripts/setup-skills.js"
   ],
   "type": "module",
   "main": "dist/index.mjs",
@@ -61,7 +64,7 @@
     "vitest": "3.2.4"
   },
   "peerDependencies": {
-    "@atscript/core": "^0.1.19"
+    "@atscript/core": "^0.1.20"
   },
   "build": [
     {},
@@ -81,6 +84,8 @@
   ],
   "scripts": {
     "pub": "pnpm publish --access public",
-    "test": "vitest"
+    "test": "vitest",
+    "setup-skills": "node ./scripts/setup-skills.js",
+    "postinstall": "node ./scripts/setup-skills.js --postinstall"
   }
 }

package/scripts/setup-skills.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/* prettier-ignore */
+import fs from 'fs'
+import path from 'path'
+import os from 'os'
+import { fileURLToPath } from 'url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+const SKILL_NAME = 'atscript-typescript'
+const SKILL_SRC = path.join(__dirname, '..', 'skills', SKILL_NAME)
+
+if (!fs.existsSync(SKILL_SRC)) {
+  console.error(`No skills found at ${SKILL_SRC}`)
+  console.error('Add your SKILL.md files to the skills/' + SKILL_NAME + '/ directory first.')
+  process.exit(1)
+}
+
+const AGENTS = {
+  'Claude Code': { dir: '.claude/skills',   global: path.join(os.homedir(), '.claude', 'skills') },
+  'Cursor':      { dir: '.cursor/skills',   global: path.join(os.homedir(), '.cursor', 'skills') },
+  'Windsurf':    { dir: '.windsurf/skills', global: path.join(os.homedir(), '.windsurf', 'skills') },
+  'Codex':       { dir: '.codex/skills',    global: path.join(os.homedir(), '.codex', 'skills') },
+  'OpenCode':    { dir: '.opencode/skills', global: path.join(os.homedir(), '.opencode', 'skills') },
+}
+
+const args = process.argv.slice(2)
+const isGlobal = args.includes('--global') || args.includes('-g')
+const isPostinstall = args.includes('--postinstall')
+let installed = 0, skipped = 0
+const installedDirs = []
+
+for (const [agentName, cfg] of Object.entries(AGENTS)) {
+  const targetBase = isGlobal ? cfg.global : path.join(process.cwd(), cfg.dir)
+  const agentRootDir = path.dirname(cfg.global) // Check if the agent has ever been installed globally
+
+  // In postinstall mode: silently skip agents that aren't set up globally
+  if (isPostinstall || isGlobal) {
+    if (!fs.existsSync(agentRootDir)) { skipped++; continue }
+  }
+
+  const dest = path.join(targetBase, SKILL_NAME)
+  try {
+    fs.mkdirSync(dest, { recursive: true })
+    fs.cpSync(SKILL_SRC, dest, { recursive: true })
+    console.log(`✅  ${agentName}: installed to ${dest}`)
+    installed++
+    if (!isGlobal) installedDirs.push(cfg.dir + '/' + SKILL_NAME)
+  } catch (err) {
+    console.warn(`⚠️   ${agentName}: failed — ${err.message}`)
+  }
+}
+
+// Add locally-installed skill dirs to .gitignore
+if (!isGlobal && installedDirs.length > 0) {
+  const gitignorePath = path.join(process.cwd(), '.gitignore')
+  let gitignoreContent = ''
+  try { gitignoreContent = fs.readFileSync(gitignorePath, 'utf8') } catch {}
+  const linesToAdd = installedDirs.filter(d => !gitignoreContent.includes(d))
+  if (linesToAdd.length > 0) {
+    const hasHeader = gitignoreContent.includes('# AI agent skills')
+    const block = (gitignoreContent && !gitignoreContent.endsWith('\n') ? '\n' : '')
+      + (hasHeader ? '' : '\n# AI agent skills (auto-generated by setup-skills)\n')
+      + linesToAdd.join('\n') + '\n'
+    fs.appendFileSync(gitignorePath, block)
+    console.log(`📝  Added ${linesToAdd.length} entries to .gitignore`)
+  }
+}
+
+if (installed === 0 && isPostinstall) {
+  // Silence is fine — no agents present, nothing to do
+} else if (installed === 0 && skipped === Object.keys(AGENTS).length) {
+  console.log('No agent directories detected. Try --global or run without it for project-local install.')
+} else if (installed === 0) {
+  console.log('Nothing installed. Run without --global to install project-locally.')
+} else {
+  console.log(`\n✨  Done! Restart your AI agent to pick up the "${SKILL_NAME}" skill.`)
+}

package/skills/atscript-typescript/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: atscript-typescript
+description: Atscript TypeScript language extension — .as file syntax, code generation, runtime type system, validation, and utilities for the Atscript metadata description language.
+---
+
+# @atscript/typescript
+
+Atscript is a universal type and metadata description language. `@atscript/typescript` is the TypeScript language extension that compiles `.as` files into `.d.ts` type declarations and `.js` runtime modules with full metadata, validation, and JSON Schema support.
+
+## How to use this skill
+
+Read the domain file that matches the task. Do not load all files — only what you need.
+
+| Domain | File | Load when… |
+|--------|------|------------|
+| Setup & configuration | [core.md](core.md) | Installing, configuring `atscript.config.ts`, using the `tsPlugin`, running the CLI |
+| `.as` file syntax | [syntax.md](syntax.md) | Writing `.as` files — interfaces, types, imports/exports, property syntax |
+| Annotations & primitives | [annotations.md](annotations.md) | Using built-in `@meta.*`/`@expect.*` annotations, defining custom annotations or primitives |
+| Code generation | [codegen.md](codegen.md) | Understanding what `.d.ts` and `.js` files are generated, `atscript.d.ts` global types |
+| Runtime type system | [runtime.md](runtime.md) | Reading/writing metadata, walking type definitions, understanding `TAtscriptAnnotatedType` |
+| Validation | [validation.md](validation.md) | Validating data, type guards, error handling, custom validator plugins |
+| Utility functions | [utilities.md](utilities.md) | Serialization, flattening, JSON Schema, `createDataFromAnnotatedType`, `forAnnotatedType` |
+
+## Quick reference
+
+```ts
+// Main export (plugin for atscript.config)
+import tsPlugin from '@atscript/typescript'
+
+// Runtime utilities (used in app code)
+import {
+  defineAnnotatedType, isAnnotatedType, annotate,
+  Validator, ValidatorError,
+  buildJsonSchema, fromJsonSchema,
+  serializeAnnotatedType, deserializeAnnotatedType,
+  flattenAnnotatedType, createDataFromAnnotatedType,
+  forAnnotatedType,
+} from '@atscript/typescript/utils'
+
+// CLI
+// npx asc -f dts        — generate .d.ts files
+// npx asc -f js         — generate .js files (not usually needed with unplugin)
+// npx asc               — generate default formats (for typescript plugin this is d.ts only, but if there are other language plugins it may generate multiple formats)
+```