@facelessad/cli 1.0.1 → 1.1.0

package/README.md

@@ -18,13 +18,56 @@ The key is stored in `~/.facelessad/config.json` with mode 0600. The
 environment variable `FACELESSAD_API_KEY` always wins — that is the way CI
 should authenticate. `FACELESSAD_API_URL` overrides the API base.
 
-`--wait` polls and prints phase + elapsed time, and gives up after 30
-minutes (`--timeout <seconds>` changes that). A video whose status is
+`--wait` polls and prints phase + elapsed time, and stops watching after 6
+hours (`--timeout <seconds>` changes that; `--timeout 0` waits with no
+limit). **Stopping the wait never cancels the build** — API videos run on a
+bulk lane that can take hours when the queue is busy, and they keep going. A video whose status is
 `draft` is not building and will never finish on its own, so `--wait`
 stops on it immediately instead of polling forever. For long-running
 builds a webhook is still the better tool — a stuck shell is a stuck CI
 job. See https://facelessad.com/developers → Webhooks.
 
+## Custom style (1.1.0)
+
+Most tools accept a look of your own instead of one of the built-in styles.
+`facelessad tools` marks which ones (`supports.customStyle`):
+
+```bash
+facelessad create --tool motion-graphics --url https://your-product.com \
+  --style custom \
+  --custom-style "Retro terminal — phosphor green on near-black, scan lines, chunky mono type" --wait
+```
+
+What to describe depends on what the tool builds. Animated Ad, Character,
+Music Video, Inspiration, Motivational and Slideshow render images, so
+describe the illustration or cinematic style. Motion Graphics, SaaS UI Ad,
+Text Animation and Video Banner generate their graphics as code, so describe
+typography, palette and motion. Crude Drawings has no custom style.
+
+Product Showcase builds both — cinematic clips animated from your real
+product photo, and text graphics drawn in code on top — so it takes two
+descriptions:
+
+```bash
+facelessad create --tool product-showcase --product-image https://.../bottle.jpg \
+  --text "A steel bottle that keeps drinks cold for 24 hours" \
+  --style custom \
+  --custom-style "Frozen tundra — cracked ice, pale blue rim light, slow orbiting camera" \
+  --custom-graphics-style "Deep navy typography, thin white hairlines — the video reads light" --wait
+```
+
+Leave `--custom-graphics-style` out and it is written for you from the first
+description.
+
+Your text is expanded into a full style specification before the video is
+built. `facelessad status <id> --json` returns the expanded text as
+`customStyle`; feed it back with `--no-refine-style` to give a whole
+campaign one identical look.
+
+`--style-hint` is now an alias: with no `--style`, it is treated exactly like
+`--custom-style`. Before 1.1.0 it only reached the script writer and could
+not change how the video looked.
+
 ## Flag spellings (1.0.1)
 
 Both spellings are accepted, because the older ones appeared on the

package/index.js

@@ -111,6 +111,10 @@ if (flags['no-music'] === true) { flags.music = 'false'; delete flags['no-music'
  */
 const KNOWN_FLAGS = new Set([
   'tool', 'url', 'text', 'duration', 'aspect', 'language', 'style', 'style-hint',
+  // 1.1.0 (§673): custom style. --style custom yksin ei riita — palvelin
+  // vastaa custom_style_required, ja se on tarkoitus: tyylin sisalto ON
+  // kayttajan teksti.
+  'custom-style', 'custom-graphics-style', 'no-refine-style',
   'structure', 'hook', 'video-mode', 'brand-color', 'brand-name', 'cta', 'name',
   'voice', 'gender', 'no-voice', 'music', 'sfx', 'captions', 'product-image',
   'no-brand-kit', 'no-winners', 'brand-kit',
@@ -220,6 +224,13 @@ function buildBody() {
   set('language', flags.language !== undefined ? String(flags.language) : undefined);
   set('style', flags.style !== undefined ? String(flags.style) : undefined);
   set('style_hint', flags['style-hint'] !== undefined ? String(flags['style-hint']) : undefined);
+  // 1.1.0 (§673): oma tyyli. --custom-style on ainoa lippu joka oikeasti
+  // vaihtaa videon ilmeen; --style-hint on nykyaan sen alias silloin kun
+  // --style on antamatta. --custom-graphics-style koskee vain
+  // product-showcasea (video + sen paalle koodilla piirretyt grafiikat).
+  set('custom_style', flags['custom-style'] !== undefined ? String(flags['custom-style']) : undefined);
+  set('custom_graphics_style', flags['custom-graphics-style'] !== undefined ? String(flags['custom-graphics-style']) : undefined);
+  if (flags['no-refine-style'] === true) body.custom_style_refine = false;
   set('ad_structure', flags.structure !== undefined ? String(flags.structure) : undefined);
   set('hook_formula', flags.hook !== undefined ? String(flags.hook) : undefined);
   set('video_mode', flags['video-mode'] !== undefined ? String(flags['video-mode']) : undefined);
@@ -392,13 +403,18 @@ Commands:
 
 Create flags:
   --tool --url --text --duration --aspect --language --style --style-hint
+  --custom-style "<look you want>"  (with --style custom; see facelessad tools)
+  --custom-graphics-style "<...>"   (product-showcase only)
+  --no-refine-style                 (use your text verbatim, don't expand it)
   --structure --hook --video-mode --brand-color --brand-name --cta --name
   --voice --gender --no-voice --music --sfx --captions --product-image
   --no-brand-kit --no-winners --brand-kit <id> (see: facelessad brands)
   --file body.json (base body; flags override)   --dry-run (print, don't send)
 
---wait gives up after 30 minutes; --timeout <seconds> changes that. A video
-in "draft" is not building and is never waited on.
+--wait stops watching after 6 hours; --timeout <seconds> changes that and
+--timeout 0 waits with no limit. Stopping the wait never cancels the build.
+A video in "draft" is not building and is never waited on. For overnight
+runs a webhook beats leaving a terminal open — see ${API}/developers.
 
 Accepted spellings: --brand = --brand-name, --color = --brand-color,
 --voice-id = --voice, --voice-gender = --gender, --no-voice-over = --no-voice,
@@ -412,10 +428,26 @@ see ${API}/developers.
   },
 };
 
+/**
+ * 1.0.2 — kaksi siistimistä ihmisluettavaan tulosteeseen.
+ *
+ * 1. VAIHE PIILOON KUN VALMIS. Rivi luki "done (render_queued)", mikä näyttää
+ *    ristiriitaiselta. Se ei ole vika: final-render menee omaan jonoonsa eikä
+ *    sen valmistuminen kirjoita terminaalivaihetta Redisiin (§471 rakentaa
+ *    jonokaton laskennan tämän varaan), joten `phase` jää viimeiseen
+ *    kirjoitettuun arvoon. `status` on silti oikein. Kun ajo on päättynyt,
+ *    vaihe ei kerro mitään hyödyllistä, joten sitä ei näytetä.
+ * 2. PRESIGNED-URL EI IHMISELLE. Se on ~500 merkkiä ja rivittyy terminaalissa
+ *    lukukelvottomaksi, eikä sitä voi lyhentää — allekirjoitus on osa URLia ja
+ *    katkaistu linkki ei toimi. Ihmiselle näytetään komento joka hakee saman
+ *    tiedoston; koneelle `--json` kantaa `url`-kentän ennallaan.
+ */
 function statusLine(d) {
+  const done = d.status === 'done' || d.status === 'failed' || d.status === 'draft';
   let s = 'Video ' + d.id + ': ' + bold(d.status);
-  if (d.phase) s += ' ' + dim('(' + d.phase + ')');
-  if (d.url) s += '\nURL (valid ~1 h): ' + d.url;
+  if (d.phase && !done) s += ' ' + dim('(' + d.phase + ')');
+  if (d.url) s += '\n' + dim('Download: ') + 'facelessad download ' + d.id + ' --out ad.mp4'
+    + '\n' + dim('(the direct link is in --json output; it expires in ~1 h)');
   if (d.error) s += '\n' + d.error;
   return s;
 }
@@ -436,7 +468,20 @@ function statusLine(d) {
  * Oletuskatto on 30 min; --timeout <sekuntia> muuttaa sen. Aikakatto poistuu
  * koodilla 1, koska pipeline ei saa jatkaa videolla jota ei ole.
  */
-const WAIT_TIMEOUT_DEFAULT = 1800;
+/**
+ * 1.0.2 — aikakatto uusiksi. 1.0.1:n 30 min oli liian tiukka: API-ajot menevät
+ * bulk-kaistalle joka etenee vasta kun käyttöliittymän jonot ovat tyhjät, ja
+ * kuvamallit ovat ajoittain hyvin hitaita. Yön yli jonottaminen on
+ * nimenomainen tuotelupaus, eikä odotuskomennon oletus saa olla sitä vastaan.
+ *
+ * Oletus on nyt 6 h ja `--timeout 0` odottaa rajattomasti. Rajaton on
+ * SALLITTU mutta ei oletus: 1.0.0:n ikuinen silmukka oli vika koska se ei
+ * ollut kenenkään valinta — nyt se on.
+ *
+ * Aikakatto EI peruuta buildia. Se lopettaa vain odottamisen, ja viesti sanoo
+ * sen. Yön yli -ajoihin oikea työkalu on silti webhook, ei auki jätetty pääte.
+ */
+const WAIT_TIMEOUT_DEFAULT = 21600;
 const POLL_SECONDS = 5;
 
 async function waitFor(id) {
@@ -444,15 +489,15 @@ async function waitFor(id) {
   // 1.0.1: --timeout luetaan sellaisenaan. Ensimmäinen versio tästä pakotti
   // lattian 30 s:aan, jolloin `--timeout 12` odotti 30 s eikä kertonut siitä
   // — sama hiljainen ylikirjoitus jota tämä paketti on täynnä korjaamassa.
-  // Nyt kelpaamaton arvo on VIRHE ja kelvollinen tehdään sellaisenaan;
-  // alaraja on yksi pollausväli, koska sitä lyhyempi ei ehdi kysyä kertaakaan.
+  // Nyt kelpaamaton arvo on VIRHE ja kelvollinen tehdään sellaisenaan.
   let limit = WAIT_TIMEOUT_DEFAULT;
   if (flags.timeout !== undefined && flags.timeout !== true) {
     limit = Number(flags.timeout);
-    if (!Number.isFinite(limit) || limit < POLL_SECONDS) {
-      die('--timeout must be a number of seconds, at least ' + POLL_SECONDS, 'invalid_timeout');
+    if (!Number.isFinite(limit) || (limit !== 0 && limit < POLL_SECONDS)) {
+      die('--timeout must be 0 (wait forever) or at least ' + POLL_SECONDS + ' seconds', 'invalid_timeout');
     }
   }
+  const noLimit = limit === 0;
   let last = '';
   for (;;) {
     const d = await call('GET', '/api/v1/videos/' + encodeURIComponent(id));
@@ -475,9 +520,10 @@ async function waitFor(id) {
       else { process.stderr.write('Error: ' + msg + '\n'); }
       process.exit(1);
     }
-    if (elapsed + POLL_SECONDS > limit) {
-      const msg = 'Gave up waiting for video ' + id + ' after ' + elapsed + 's (last status: ' + d.status
-        + (d.phase ? ' — ' + d.phase : '') + '). The build may still finish; check with: facelessad status ' + id;
+    if (!noLimit && elapsed + POLL_SECONDS > limit) {
+      const msg = 'Stopped waiting for video ' + id + ' after ' + elapsed + 's (last status: ' + d.status
+        + (d.phase ? ' — ' + d.phase : '') + '). The build was NOT cancelled and is still running — '
+        + 'check it with: facelessad status ' + id + '   (or wait longer with --timeout 0)';
       if (asJson) { process.stdout.write(JSON.stringify({ ...d, ok: false, code: 'wait_timeout' }) + '\n'); }
       else { process.stderr.write('Error: ' + msg + '\n' + dim('wait_timeout') + '\n'); }
       process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@facelessad/cli",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Create faceless video ads from your terminal or build scripts — the FacelessAd command line.",
   "license": "MIT",
   "type": "module",