ticbuild 1.0.0

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "ticbuild",
+  "version": "1.0.0",
+  "description": "A build & watch system for TIC-80",
+  "main": "dist/index.js",
+  "bin": {
+    "ticbuild": "./dist/index.js"
+  },
+  "scripts": {
+    "prepare": "cross-env NODE_ENV=production npm run build",
+    "prebuild": "node scripts/gen-build-info.js",
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "start": "node dist/index.js",
+    "dev": "tsc && node dist/index.js",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "keywords": [
+    "tic80",
+    "build",
+    "watch",
+    "cli"
+  ],
+  "author": "Carl Corcoran",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thenfour/ticbuild"
+  },
+  "license": "ISC",
+  "devDependencies": {
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "cross-env": "^10.1.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "@types/chokidar": "^2.1.7",
+    "@types/luaparse": "^0.2.13",
+    "ajv": "^8.12.0",
+    "chalk": "^4.1.2",
+    "chokidar": "^3.6.0",
+    "commander": "^11.0.0",
+    "dotenv": "^16.0.0",
+    "jsonc-parser": "^3.2.0",
+    "luaparse": "^0.3.1"
+  }
+}

package/templates/help/build.txt

@@ -0,0 +1,23 @@
+
+ticbuild build
+
+usage: ticbuild build [manifest] [<args>]
+
+Build a TIC-80 cart from a manifest file
+
+Arguments:
+
+  [manifest]           Path to manifest file (default: first *.ticbuild.jsonc)
+
+Options:
+
+  -m, --mode <name>    Build configuration name from manifest
+  -v, --var <key=value> Override manifest variable (can be used multiple times)
+  -h, --help           Show this help message
+
+Examples:
+
+  ticbuild build
+  ticbuild build game.ticbuild.jsonc
+  ticbuild build --mode release
+  ticbuild build --var DEBUG=false --var VERSION=1.0

package/templates/help/init.txt

@@ -0,0 +1,23 @@
+
+ticbuild init
+
+usage: ticbuild init [options] [dir]
+
+Initialize a new ticbuild project with a template
+
+Arguments:
+
+  [dir]                Directory to initialize (default: current directory)
+
+Options:
+
+  -n, --name <name>    Project name (used in manifest)
+  -t, --template <name> Template name: 'minimal' or 'example' (default: example)
+  -f, --force          Overwrite existing files
+  -h, --help           Show this help message
+
+Examples:
+
+  ticbuild init
+  ticbuild init ./myproject --name "My Game"
+  ticbuild init . --template minimal --force

package/templates/help/main.txt

@@ -0,0 +1,41 @@
+
+ticbuild {{VERSION}}
+  commit: {{COMMIT_HASH}}
+  built: {{BUILD_DATE}}
+
+usage: ticbuild [-h | --help] [-v | --version] <command> [<args>]
+
+A build and watch system for TIC-80 development
+
+Common commands:
+
+  build, b [manifest]         Build a TIC-80 cart from manifest
+  run, r [manifest]           Build and launch TIC-80
+  watch, w [manifest]         Build, launch, and watch for changes
+  init [dir]                  Initialize a new project
+
+Other commands:
+
+  tic80, t                    Launch TIC-80 directly
+  help [command]              Show help for a specific command
+
+Use 'ticbuild help <command>' or 'ticbuild <command> --help' for detailed help.
+
+Examples:
+
+  ticbuild build
+    Build using first *.ticbuild.jsonc file in current directory
+
+  ticbuild watch my.ticbuild.jsonc
+    Build and watch a specific manifest file
+
+  ticbuild init ./myproject --name "My Game"
+    Initialize a new project in the specified directory
+
+  ticbuild build --mode release
+    Build using the 'release' build configuration
+
+Links:
+
+  GitHub:  https://github.com/thenfour/ticbuild
+  Somatic: https://somatic.tenfourmusic.net

package/templates/help/run.txt

@@ -0,0 +1,22 @@
+
+ticbuild run
+
+usage: ticbuild run [options] [manifest]
+
+Build a TIC-80 cart and launch it in TIC-80
+
+Arguments:
+
+  [manifest]           Path to manifest file (default: first *.ticbuild.jsonc)
+
+Options:
+
+  -m, --mode <name>    Build configuration name from manifest
+  -v, --var <key=value> Override manifest variable (can be used multiple times)
+  -h, --help           Show this help message
+
+Examples:
+
+  ticbuild run
+  ticbuild run game.ticbuild.jsonc
+  ticbuild run --mode debug

package/templates/help/tic80.txt

@@ -0,0 +1,8 @@
+
+ticbuild tic80
+
+usage: ticbuild tic80
+
+Launch TIC-80 directly without building a cart
+
+This is a convenience command to quickly open TIC-80.

package/templates/help/watch.txt

@@ -0,0 +1,24 @@
+
+ticbuild watch
+
+usage: ticbuild watch [options] [manifest]
+
+Build a TIC-80 cart, launch it, and watch for changes
+
+When source files or the manifest change, the cart is automatically
+rebuilt and TIC-80 is relaunched with the updated cart.
+
+Arguments:
+
+  [manifest]           Path to manifest file (default: first *.ticbuild.jsonc)
+
+Options:
+
+  -m, --mode <name>    Build configuration name from manifest
+  -v, --var <key=value> Override manifest variable (can be used multiple times)
+  -h, --help           Show this help message
+
+Examples:
+
+  ticbuild watch
+  ticbuild watch game.ticbuild.jsonc --mode debug

package/templates/minimal/project.ticbuild.jsonc

@@ -0,0 +1,43 @@
+// paths are always relative to the manifest file's dir (which defines the project root dir)
+{
+    "$schema": "./ticbuild.schema.json",
+    "project": {
+        "name": "{{PROJECT_NAME}}",
+        "includeDirs": [
+            "./src"
+        ],
+        "importDirs": [
+            "./assets"
+        ],
+        "binDir": "./dist/bin",
+        "objDir": "./dist/obj",
+        "outputCartName": "$(project.name).tic",
+    },
+    "variables": {},
+    "imports": [
+        {
+            "name": "maincode",
+            "path": "src/main.lua",
+            "kind": "LuaCode",
+        },
+    ],
+    "assembly": {
+        "lua": {
+            "minify": true,
+            "globals": {
+                "PROJECT_NAME": "$(project.name)",
+            },
+        },
+        "blocks": [
+            {
+                "chunks": [
+                    "CODE"
+                ],
+                "asset": "maincode",
+                "code": {
+                    "emitGlobals": true,
+                }
+            },
+        ],
+    },
+}

package/ticbuild.schema.json

@@ -0,0 +1,327 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "TIC-80 Build Manifest",
+  "description": "Configuration file for ticbuild projects",
+  "type": "object",
+  "required": [
+    "project",
+    "imports",
+    "assembly"
+  ],
+  "properties": {
+    "project": {
+      "type": "object",
+      "required": [
+        "name",
+        "binDir",
+        "objDir",
+        "outputCartName"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Project name"
+        },
+        "includeDirs": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Directories to include in source file lookup"
+        },
+        "importDirs": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Directories to include in resource import lookup"
+        },
+        "binDir": {
+          "type": "string",
+          "description": "Output directory for built cartridges"
+        },
+        "objDir": {
+          "type": "string",
+          "description": "Output directory for build artifacts"
+        },
+        "outputCartName": {
+          "type": "string",
+          "description": "Name of the output cartridge file"
+        }
+      }
+    },
+    "variables": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "User-defined variables for substitution"
+    },
+    "imports": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "name"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Symbolic identifier for this import"
+          },
+          "path": {
+            "type": "string",
+            "description": "Path to the source file or cartridge"
+          },
+          "value": {
+            "type": "string",
+            "description": "Inline value for text or encoded binary imports"
+          },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "LuaCode",
+              "Tic80Cartridge",
+              "binary",
+              "text"
+            ],
+            "description": "Type of import"
+          },
+          "sourceEncoding": {
+            "type": "string",
+            "enum": [
+              "raw",
+              "lz",
+              "hex",
+              "b85+1",
+              "lz85+1"
+            ],
+            "description": "Source encoding for binary imports"
+          },
+          "chunks": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "TILES",
+                "MAP",
+                "CODE",
+                "FLAGS",
+                "SFX",
+                "WAVEFORMS",
+                "PALETTE",
+                "MUSIC_TRACKS",
+                "MUSIC_PATTERNS",
+                "CODE_COMPRESSED",
+                "DEFAULT",
+                "SCREEN",
+                "CODE_WASM"
+              ]
+            },
+            "description": "Specific chunks to import from cartridges"
+          }
+        },
+        "anyOf": [
+          {
+            "required": [
+              "path"
+            ]
+          },
+          {
+            "required": [
+              "value"
+            ]
+          }
+        ]
+      },
+      "description": "Import definitions for external assets"
+    },
+    "assembly": {
+      "type": "object",
+      "required": [
+        "blocks"
+      ],
+      "properties": {
+        "lua": {
+          "type": "object",
+          "properties": {
+            "minify": {
+              "type": "boolean",
+              "description": "Whether to minify Lua code"
+            },
+            "minification": {
+              "type": "object",
+              "properties": {
+                "stripComments": {
+                  "type": "boolean"
+                },
+                "maxIndentLevel": {
+                  "type": "number"
+                },
+                "lineBehavior": {
+                  "type": "string",
+                  "enum": [
+                    "pretty",
+                    "tight",
+                    "single-line-blocks"
+                  ]
+                },
+                "maxLineLength": {
+                  "type": "number"
+                },
+                "aliasRepeatedExpressions": {
+                  "type": "boolean"
+                },
+                "renameLocalVariables": {
+                  "type": "boolean"
+                },
+                "aliasLiterals": {
+                  "type": "boolean"
+                },
+                "packLocalDeclarations": {
+                  "type": "boolean"
+                },
+                "simplifyExpressions": {
+                  "type": "boolean"
+                },
+                "removeUnusedLocals": {
+                  "type": "boolean"
+                },
+                "removeUnusedFunctions": {
+                  "type": "boolean"
+                },
+                "functionNamesToKeep": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "renameTableFields": {
+                  "type": "boolean"
+                },
+                "tableEntryKeysToRename": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "description": "Minification options (OptimizationRuleOptions)"
+            },
+            "globals": {
+              "type": "object",
+              "additionalProperties": {
+                "oneOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "boolean"
+                  }
+                ]
+              },
+              "description": "Global variables to emit as local declarations at the top of Lua code"
+            }
+          }
+        },
+        "blocks": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "asset"
+            ],
+            "properties": {
+              "chunks": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "enum": [
+                    "TILES",
+                    "SPRITES",
+                    "MAP",
+                    "CODE",
+                    "FLAGS",
+                    "SFX",
+                    "WAVEFORMS",
+                    "PALETTE",
+                    "MUSIC_TRACKS",
+                    "MUSIC_PATTERNS",
+                    "CODE_COMPRESSED",
+                    "DEFAULT",
+                    "SCREEN",
+                    "CODE_WASM"
+                  ]
+                }
+              },
+              "bank": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 7,
+                "description": "Bank index (defaults to 0)"
+              },
+              "asset": {
+                "oneOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "object",
+                    "required": [
+                      "import"
+                    ],
+                    "properties": {
+                      "import": {
+                        "type": "string"
+                      },
+                      "chunks": {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  }
+                ]
+              },
+              "code": {
+                "type": "object",
+                "properties": {
+                  "emitGlobals": {
+                    "type": "boolean",
+                    "description": "Whether to emit assembly.lua.globals for this code block"
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "description": "Assembly configuration"
+    },
+    "buildConfigurations": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "project": {
+            "type": "object"
+          },
+          "variables": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
+          "assembly": {
+            "type": "object"
+          }
+        }
+      },
+      "description": "Build configuration overrides"
+    }
+  }
+}